• Contribution checklist

A contribution to the GLIBC project should always be sent to the appropriate mailing list for the contribution scope:

• libc-alpha
• libc-ports
• libc-locale

In addition, a bugzilla entry for a bug may be created and should contain everything a high-quality mailing list submission would contain.

Mailing List Moderation

The libc-alpha mailing list is moderated in order to improve the quality of the contribution submissions to the mailing list.

• If your contribution is moderated in a mailing list queue please follow the directions in the moderation email. Please do not attempt to converse with the moderator unless you feel you've been unjustly moderated.

• Follow the instruction in the moderation email. We want to help you!

• If you need help with formulating a proper contribution, or are directed to; please use the libc-help mailing list.

• If you simply need to re-spin the patch due to some oversight please do so and resubmit to the libc-alpha mailing list as if it were an email destined for the mailing list, i.e. don't attempt to converse with the moderator or your conversational email will be moderated.

Contribution Guidelines

A high-quality contribution includes the following things:

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>

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.

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.

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.

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.

Out-of-Scope (Automatically Generated Files)

Changes in automatically regenerated files (configure, for example) should not be included in the submitted patch.

Detailed Explanation of the Patch

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.

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. If your proposed contribution changes a fundamental provision of the locale you may need to demonstrate one or all of the following:

• cite authoritative reference
• demonstrate qualification to make the change
• get permission from the original locale creator
• create a bugzilla entry for the change (and post to the libc-locale mailing list).

These rules (sans the last parenthetical rule) are highlighted in the following post by the GLIBC maintainer:

Re: [PATCH] [et_EE]: Set first_{week,work}day to monday

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.

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

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

1. To add 'year6' following 'year5' simply add ', year6' between 'year5' and the copyright-holder, e.g.,:

     Copyright (C) year1, year5, year6  copyright-holder

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

1. Do NOT abbreviate dates into two digit year format, i.e., don't abbreviate '2000' as '08'. As indicated in this thread on libc-alpha, the maintainer does not like the two-digit year format.

Attribution

• When you create a new file you need to attribute the changes to yourself even if you submitted them on behalf of your company. Your copyright assignment is on file with the Free Software Foundation so we know who assigned the copyright to the sources you contributed, be it yourself or a company.

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.

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

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.

Properly Formatted Changes

Nested C preprocessor directives 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

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 .