Say that it's the strong preference to include the patch as part of the text of the email.
|Deletions are marked like this.||Additions are marked like this.|
|Line 296:||Line 296:|
| * You can include the patch as part of the text of the email; that's often easier.
* If your mailer insists on wrapping long lines or otherwise altering patch contents, or if the diff might cause problems due to binary data or mixed encodings, attach the patch to the email. The attachment should normally employ a Content-Type of text/x-diff or text/x-patch (or at least text/plain) and a charset of UTF-8 or US-ASCII; if it contains binary data or mixed encoding it may need to specify a Content-Type of application/octet-stream instead. Please use an attachment file name that ends in ".diff" or ".patch" (or at least ".txt").
|* The strong preference is that you include the patch as part of the text of the email. However, if your mailer unavoidably wraps long lines or otherwise alters patch contents, or if the diff might cause problems due to binary data or mixed encodings, attach the patch to the email. The attachment should normally employ a Content-Type of text/x-diff or text/x-patch (or at least text/plain) and a charset of UTF-8 or US-ASCII; if it contains binary data or mixed encoding it may need to specify a Content-Type of application/octet-stream instead. Please use an attachment file name that ends in ".diff" or ".patch" (or at least ".txt").|
- Bugzilla entry
- Contribution Email Subject Line
- Properly Identified Contribution Scope
- Detailed Explanation of the Patch
- Check For New Warnings
- Try to Identify Related Changes
- FSF copyright Assignment
- Update Copyright Information
- Properly Formatted GNU ChangeLog
- Properly Formatted Changes
- Proper Formatted Unified diff of the Changes
- Ping and keep pinging
A contribution to the GLIBC project should always be sent to the appropriate mailing list for the contribution scope:
- libc-alpha (Core GLIBC)
- libc-ports (Additional community maintained add-ons)
- libc-locale (Locale changes)
- libc-help (Need help)
A high-quality contribution includes the following things:
1. Bugzilla entry
A bugzilla entry for a bug should be created and *should* contain everything a high-quality mailing list submission would contain.
If your contribution fixes a user-visible issue we strongly suggest it should have a bugzilla entry.
Please follow the bugzilla procedures.
2. Contribution Email Subject Line
A high-quality email subject line for a contribution contains the following tags:
For a Single patch contribution:
For Multi-part patch set contributions where [PATCH 0/2] is used to described the forth coming patches:
[PATCH 0/2] <Optional unique prefix e.g. "String cleanup:"><Subject related to the patch set e.g. Cleanup all broken string routines.>
[PATCH 1/2] <Optional unique prefix e.g. "String cleanup:"><Distinct subject line for this patch e.g. Cleanup strstr.>
[PATCH 2/2] <Optional unique prefix e.g. "String cleanup:"><Another distinct subject line for this patch e.g. Cleanup strncmp.>
For a request for comments that doesn't have to be a patch at all:
For a request for comments on a patch or patch set:
For a patch that fixes a bug filed in bugzilla:
[PATCH][BZ <bugzilla number>] <Subject>
For a patch that affects a particular architecture only:
[PATCH] PowerPC - <Subject>
For a patch that is the Nth version of an earlier patch:
For a patch carried on a non-canonical namespace branch, but not necessary in-line in the patch body:
[PATCH namespace/branch] <Subject>, e.g., [PATCH roland/arm-memcpy] ARM: Make multiarch memcpy always use NEON when compiler does
For a patch that is already committed:
3. Properly Identified Contribution Scope
Before you generate a patch or edit a ChangeLog file run find . -name ChangeLog to help identify the scope of your contribution, e.g.,
./nptl/ChangeLog ./posix/glob/ChangeLog ./ports/ChangeLog ./localedata/ChangeLog ./libidn/ChangeLog ./nptl_db/ChangeLog ./ChangeLog
If you've touched code in any of the directories these ChangeLogs are found you can use the directory(s) to identify the scope(s) of the patch.
If you have modified code in more than one than one scope you need to generate separate patch sets and separate ChangeLog entries for each scope.
- If possible keep a patch to a single scope. Exceptions would be for locking constructs which have implementations in NPTL and Base.
- Never mix Base and Ports fixes in a single patch.
- Any modification to code not in the Ports or Add-ons scope should be considered part of GLIBC base scope.
- Send base scope patches to the libc-alpha mailing list.
The project toplevel ChangeLog is for anything in the base scope that doesn't have it's own ChangeLog.
All entries for the toplevel ChangeLog file should be relative to the base directory and all patches under this scope should apply with patch -p1.
3.2. Add-Ons (NPTL, localedata, posix, libidn, et al)
- Patches to add-on projects (like NPTL) should be sent to the libc-alpha mailing list.
Add-ons have their own ChangeLog files so any changes to the add-on directory should be indicated in <add-on>/ChangeLog.
All entries for the <add-on>/ChangeLog file should be relative to the <add-on>/ directory, for example, an entry for nptl/sysdeps/pthread/pthread_sigmask.c would be the following,
2010-10-14 Random Developer <email@example.com> * sysdeps/pthread/pthread_sigmask.c (some_routine): Made some modification.
All Add-on patches should apply with patch -p0 from the base GLIBC directory. For example, the diff for nptl/sysdeps/pthread/pthread_sigmask.c would be relative to:
If your patch contains add-on (e.g., NPTL) and Base fixes provide TWO separate patch sets and two separate ChangeLog entries. These may be sent in the same patch if they're small enough but no-one will complain if you send them in two separate patches.
For locale changes to the Localedata add-on please see the Qualifications (Locales) section below.
Any modification to code in the ports/ directory is under the ports scope.
- Send ports patches to the libc-ports mailing list.
The ports/ project has its own ChangeLog file so any changes to a ports platform should be indicated in the ports/ChangeLog.
All entries for the ports/ChangeLog file should be relative to the ports/ directory and all patches should apply with patch -p1.
3.4. Out-of-Scope (Automatically Generated Files)
Changes in automatically regenerated files (configure, for example) should not be included in the submitted patch.
4. Detailed Explanation of the Patch
4.1. General Patch Requirements
- Explain the steps required to reproduce the problem.
- Extra points are awarded for a test-case which demonstrates the problem and can be used in the test-suite to demonstrate success of a fix.
- Explain the observed versus expected behaviour.
- Quote relevant standards, whenever possible give section or URL reference.
All patches for consideration must have ChangeLog entry updates (see below) of they will be rejected during mailing list moderation.
If the code in question is a Request For Comment (RFC) please indicate as such in the email subject. Explicit RFC emails aren't constrained by the ChangeLog rules but they won't be considered for inclusion until they comply.
If your patch adds a new interface then that interface should be documented in the glibc manual.
Where possible please additionally contribute a manual page to the Linux man-pages project: http://www.kernel.org/doc/man-pages/
4.3. Qualification (Locales)
Most contributions don't require explicit justification for the patch. Necessity of inclusion can be negotiated with the maintainer. One exception is Locales - the GLIBC maintainers cannot easily judge on their own if your new version is correct.
- If your proposed contribution is a non-trivial change, you should get an approval from the locale maintainer or original creator.
- In case they are unreachable or there is a dispute, you should cite authoritative references and/or multiple widely used websites (government pages or websites of major national newspapers are a good choice).
- If the change is not clear-cut, e.g. you want to switch between two common usages, it is good to gather (and link to) feedback from local user community.
5. Check For New Warnings
Check the make log for new warnings. Any new warnings generated should have the cause corrected before submission of the patch.
Explain any regressions in the test suite.
- Explain for which targets the test suite was run.
- Adding a test-case to the test suite may increase the likelihood of acceptance of your patch. In some cases it may be necessary.
6.1. Testing Locales
If you are modifying a locale, make sure it still compiles:
- localedef --no-archive -i localedata/locales/es_CU -f localedata/charmaps/UTF-8 es_CU.utf-8
This command attempts to install the compiled locale to system location and afterwards you can check further if it behaves like you want. Unfortunately, there is no easy way to load locales installed in different locations.
If you have set up glibc compilation environment, you can mass-test compilation of all locales:
- make localedata/install-locales install_root=(configure's --prefix)
(And invoking (configure's --prefix)/bin/localedef manually will of course install to the (configure --prefix).)
7. Try to Identify Related Changes
Specific functionality in glibc is often implemented separately for different configurations, such as different operating systems or processor architectures. When identifying and fixing a problem in one of these implementations, the same reasoning might also apply to the others, and the same or a similar fix might also be needed there. You should try to identify these cases, and draw attention to these in your submission (»similar changes to [this] are probably needed [here], too«), or if the case is simple enough try to fix all occurrences at the same time and propose a possibly untested patch, too. Especially for nontrivial issues, it is of course fine to defer to the respective maintainers for help -- we don't expect you to fix SPARC assembler code when you're fixing an issue in an x86 assembler implementation, and neither do we expect you to be able to test a patch for GNU/Hurd when you're fixing an issue in glibc's GNU/Linux-specific code.
8. FSF copyright Assignment
The Free Software Foundation (holder of the GLIBC copyrights) requires copyright assignment for all legally significant changes by a particular author (read not a company). This webpage describes the copyright assignment requirements.
- Explain your current FSF copyright assignment status.
In the event that you have not previously completed an FSF copyright assignment, a libc-alpha moderator or GLIBC maintainer will direct you to a FSF copyright assignment request form that's best suited to your contribution under the guidelines on this gnu.org webpage.
Copyright assignment is not required for localedata changes.
9. Update Copyright Information
When non-trivial, i.e. legally significant, changes are made to a file the copyright date must be updated in the file. This GNU Copyright-Notices webpage indicates the proper format for the copyright notice and how to update the dates:
- A copyright notice takes the following form:
Copyright (C) year1, year5 copyright-holder
To add 'year6' following 'year5' simply add ', year6' between 'year5' and the copyright-holder, e.g.,:
Copyright (C) year1, year5, year6 copyright-holder
For GLIBC, spanning of consecutive years IS allowed. Therefore, when adding a third (or more) consecutive year to the copyright statement (like 'year7'), you may replace individual consecutive years with a year range, e.g.,
Copyright (C) year1, year5-year7 copyright-holder
For GLIBC, collapsing of years between 1991 and the present IS allowed (See this thread on libc-alpha). Therefore, when adding a second (or more) years to the copyright statement (like 'year7'), you may collapse years with a year range given that the range starts at or after 1991, e.g.,
Copyright (C) year1-year7 copyright-holder
Do NOT abbreviate dates into two digit year format, i.e., don't abbreviate '2008' as '08'. As indicated in this thread on libc-alpha, the maintainer does not like the two-digit year format.
- The copyright notice of some files indicates a copyright holder other than the FSF (such files have been copied from another project). In those cases, leave the the non-FSF copyright notice as is, and add a new line for the FSF copyright. If there's already an FSF-copyright line, simply update it, adding it a year as usual. If the two copyright notices disagree for other reasons, e.g., licensing information, keep the notices separate. E.g.,
Copyright (C) 2012-2013 Free Software Foundation, Inc. ... rest of FSF copyright notice ... Copyright (C) 2010 other-copyright-holder ... rest of other copyright notice ...
"Contributed by" statements are no longer required or desired in Glibc source files (though existing statements will remain). Attribution is now recorded in git commit logs as the commit "Author". Please do not use "Contributed by" statements in your submissions.
11. Properly Formatted GNU ChangeLog
This should not be part of the change diff; put it right before the diff. (The git-show-gnu script can be used to produce the standard format for posting a patch once you've done a git commit on a local branch.)
- Files that were regenerated should be identified and the change should say "Regenerated."
The GDB folks have a tool called mklog to help generate ChangeLogs.
Per this comment, every change line in a ChangeLog should start with a capitalized word and end with a period.
The ChangeLog should indicate what was changed in the file. For instance, if you change the size of a variable you need to indicate as much in the ChangeLog.
ChangeLog standard tab-width is 8.
ChangeLog standard max-line-length is 80.
Make sure your mailer doesn't turn TABS into SPACES, i.e., turn on preformat.
An example for a trivial change follows: Note: words in arrow brackets shouldn't appear in the ChangeLog, they indicate whitespace.
When multiple entries contain the same ChangeLog information as previous entries the glibc approved shorthand is: * file: Likewise.
YYYY-MM-DD<2 spaces>John Doe<2 spaces><firstname.lastname@example.org> <blank-line> <tab--->[BZ #<number>]<use this if there is a bugzilla associated with the patch> <tab--->* login/utmp_file.c (pututline_file): Replace call to 'dup()'<line wrap at or before column 79> <tab--->with libc internal symbol '__dup()' to avoid access through<line wrap at or before column 79> <tab--->the PLT. <tab--->* manual/install.texi: Minimum version updated. <tab--->* INSTALL: Regenerated.
2008-12-12 John Doe <email@example.com> [BZ #9999] * login/utmp_file.c (pututline_file): Replace call to 'dup()' with libc internal symbol '__dup()' to avoid access through the PLT. * manual/install.texi: Minimum version updated. * INSTALL: Regenerated.
12. Properly Formatted Changes
Please see Style_and_Conventions for a full description of coding guidelines.
13. Proper Formatted Unified diff of the Changes
Only unified diff (-uNr) format is acceptable. Patches which are context diffs will not be reviewed.
- Unified diff must be in a format that can be applied with patch -p1.
- The strong preference is that you include the patch as part of the text of the email. However, if your mailer unavoidably wraps long lines or otherwise alters patch contents, or if the diff might cause problems due to binary data or mixed encodings, attach the patch to the email. The attachment should normally employ a Content-Type of text/x-diff or text/x-patch (or at least text/plain) and a charset of UTF-8 or US-ASCII; if it contains binary data or mixed encoding it may need to specify a Content-Type of application/octet-stream instead. Please use an attachment file name that ends in ".diff" or ".patch" (or at least ".txt").
If you have any questions regarding these criteria please email firstname.lastname@example.org .
14. Ping and keep pinging
If your patch is not reviewed it may just mean that the reviewers are busy. Please ping and keep pinging the patch on a weekly basis.