• Contribution checklist

Contribution Checklist

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:

• [PATCH] <Subject>

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.>

  Notes: http://sourceware.org/ml/libc-ports/2011-11/msg00025.html

For a request for comment that doesn't have to be a patch at all:

• [RFC] <Subject>

For a request for comment on a patch or patch set:

• [RFC][PATCH] <Subject>

For a patch for against a bug filed in bugzilla:

• [PATCH][BZ <bugzilla number>] <Subject>

For a patch that effects a particular architecture only:

• [PATCH] PowerPC - <Subject>

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.

3.1. Base

• 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  <developer@provider.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:

  • nptl/sysdeps/pthread/pthread_sigmask.c

• 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.

3.3. Ports

• 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.

4.2. Documentation

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.

6. Testing

• 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.

7. FSF copyright Assignment

• 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.

  • Note: the following list is quick reference links for the moderator or maintainer. They will send you the correct form.

  • request-disclaim.changes

  • request-assign.changes

  • request-assign.future

• Copyright assignment is not required for localedata changes.

8. 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.

9. Attribution

• "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.

10. Properly Formatted GNU ChangeLog

• Your ChangeLog must be in the GNU ChangeLog format. The ChangeLog format is described here and here.

• This should not be part of the change diff.
• 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 you 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.

YYYY-MM-DD<2 spaces>John Doe<2 spaces><johndoe@some.email.address>
<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  <johndoe@some.email.address>

        [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.

11. Properly Formatted Changes

11.1. 79-Column Lines

All source files in glibc must use lines of fewer than 80 characters. The only exceptions are when it's syntactically impossible to split a line for some reason.

11.2. Nested C Preprocessor Directives

These need to properly indented.

e.g.:

#if FOO
# define BAR
#endif

and not:

#if FOO
#define BAR
#endif

Note that in a header file, the outer #ifndef _FILE_H/#endif pair does not increase the indentation level.

#ifndef _FILE_H
#if FOO
# define BAR
#endif
#endif

12. 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.
• Included inline with the text of the email or as a separate attachment if your mailer wraps long lines.

If you have any questions regarding these criteria please email libc-help@sourceware.org .

13. 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.