• Contribution checklist v2

Contribution Checklist

Thank you for contributing to glibc, we hope this guide helps.

Developing a change for glibc goes through several stages including patch development, testing, commit formatting, sending to the mailing list for review, review, and finally the commit.

This guide is intended to help you through each of these steps.

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

At a Glance

Here is a high level list of things to do to get your patches into glibc. Please do read through the whole document if this is your first time contributing to glibc as there are some caveats that you may need to be mindful of for your first submission:

• Make sure you have signed papers to assign copyright to the FSF

• Clone the repository

• Hack on code in your repository

• If you're fixing a bug, file a bug report

• Test your changes
• Commit the changes into your repository, making sure to rebase on top of latest master

• Create one or more patches using git format-patch

• Use git send-email --to=libc-alpha@sourceware.org to send the patch to the list, using --cc to get the attention of specific maintainers if needed.

• Ping at least weekly if your patch has not been reviewed yet
• On approval, commit the patch if you have access, or ask the reviewer to commit for you

1. Read first

If you are contributing a new architecture port, see additional information on such contributions.

When dealing with old branches see the instructions for legacy contributions.

2. FSF copyright assignment

Even before you start developing your patch, you need to review your FSF copyright status with the project and determine if your changes need copyright assignment.

Why does the FSF get copyright assignments from contributors?

In the event that you have not previously completed an FSF copyright assignment, a glibc developer or project steward can direct you to a FSF copyright assignment request form that's best suited to your contribution under the guidelines on this gnu.org webpage. To find a glibc maintainer or project steward see the MAINTAINERS page or ask for help on libc-help.

• Note: the following list is quick reference links for developers and project stewards. They will send you the correct form.

• request-disclaim.changes

• request-assign.changes

• request-assign.future

Copyright assignment is not required for localedata changes.

Copyright assignment for commulative changes by any one author of less than 15 lines do not require copyright assignment.

For GNU C Library Stewards: Template Email for Copyright assignment issues

3. Patch development

3.1. Security

If you believe the bug could be a security issue please follow the security process. If the reporter follows the security process then the project will provide an attribution in the NEWS for the release (see Committer checklist).

3.2. Locales

If you are contributing a locale related change, please see the Locales page for additional instructions. Please pay careful attention to the Qualifications section in the Locales page.

3.3. Bugzilla entry

If your contribution fixes a user-visible defect present in a released glibc version (or has been discovered during a release freeze), it must reference a bug in Bugzilla. Please also reference any bug that has been filed even if it is not strictly needed by the preceding rule (e.g., if the change concerns an enhancement, not a defect).

Contributions must still be sent to the relevant mailing list, but the Bugzilla entry will be used to track the bug, record interactions with users, and identify the release in which the bug was fixed (used to automated release note generation).

A Bugzilla bug should contain everything a high-quality mailing list submission would contain, or a link to the relevant mailing list discussion.

Please follow the Bugzilla procedures.

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

3.5. Update copyright information

• The glibc project automatically updates copyright years on all files using scripts/update-copyrights. You do not need to update copyright years, but you may need to add a notice (see "adding a copyright notice").

• 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 leave it as-is. 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 ...

3.6. Properly Formatted Changes

Please see Style_and_Conventions for a full description of coding guidelines.

"Contributed by" statements are no longer required or desired in glibc source files (though existing statements will remain).

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

• Review any regressions in the test suite.

• Review 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. All test cases begin with a comment that contains a one line explanation of the test and the FSF copyright header.
• The test-suite contains two key types of tests, those which are run from the build tree (tests target), and those which are run in an installed tree and isolated in a container (tests-container target). Consider what you are testing and which suits your specific needs. For example testing ldconfig's ability to change system symbolic links is safer to test in an installed tree within a container.

• Consider testing with scripts/build-many-glibcs.py which exercises a build and cross-test cycle (no execution tests) for all the supported glibc configurations. In practice this is very useful to catch issues related to compiler warnings, header installation, and configuration errors. Running scripts/build-many-glibcs.py is very resource intensive and not a required step in the contribution process.

4.1. Testing Locales

Please see the Testing Locales section in the Locales page. In general you must install glibc to a temporary location e.g. make install DESTDIR=/tmp/glibc-install to compile and install all supported locales.

4.2. Check For New Warnings

We build with -Werror so new compiler warnings should fail your build, but still check the make log for other new warnings. Any new warnings generated should have the cause corrected before submission of the patch.

5. Commit formatting

When you prepare to commit your code to your local repository you must correctly format the commit message.

There are two important aspects to this, the first line, and the message body.

5.1. First line

The first line of the commit will be the same as the subject line for your email to the developer mailing list.

The first line of the commit message should contain the following:

• Subsystem (argp, malloc, etc., generally a directory name in the source tree), kernel (Linux or Hurd), or architecture (e.g., x86 for all three variants). This can be omitted for generic changes that do not fit to a particular subsystem.

• A colon (:), if the first field is present.

• A brief summary of the change (~50 characters long).

• The referenced bug(s) in Bugzilla (separated by a space from the previous) e.g. [BZ #xxxx] or (bug xxxx).

Here a some examples of commit subjects:

• nss: Add tst-nss-files-hosts-long test [BZ #21915]

• powerpc: Fix VSCR position in ucontext (bug 24088)

• oc_FR locale: Multiple updates (bug 23140, bug 23422).

• Add fall-through comments.

The first line is followed by a blank line and then the commit message body.

5.2. Commit message body

The commit message body should accurately and succinctly explain the the changes.

• Explain the steps required to reproduce the problem.
• Explain the observed versus expected behaviour.
• Explain the solution and alternatives considered.

• Explain any regressions in the test suite.

• Explain for which targets the test suite was run.
• Quote relevant standards, whenever possible give section or URL reference.

5.3. Attribution

The commit message body must also include attribution.

• Attribution is now recorded in git commit logs as the commit "Author" and via "Reviewed-by", "Suggested-by" or "Co-authored-by:" lines. The meaning of "Reviewed-by", and "Suggested-by" are identical to their meaning in the Linux kernel project. The "Co-authored-by:" lines indicate authors who contributed legally significant changes to the patch. For changes which were not legally significant consider "Suggested-by" or "Reviewed-by" (if the suggestions came from a reviewer). While the FSF does not claim any copyright interests in locale changes we still use proper attribution to give credit where it is due.

• The project does not support or use "Signed-off-by" lines because they may give the wrong impression that FSF copyright status is not required. Instead the git "Author" is the first author, and "Co-authored-by:" lines represent all subsequent authors.

• All authors of the patch must be identified, and all authors who are contributing legally significant changes are required to have copyright assignment with the FSF, see: FSF copyright assignment.

  • Attribution for changes that did not require copyright should be identified with "Copyright-paperwork-exempt: Yes".

6. Emailing your patch

6.1. Determine email recipient

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

• libc-alpha (Development list for glibc, any subsystem)
• libc-locale (Locale subsystem change discussions only. Send new patches to libc-alpha)
• libc-stable (Discussions around stable branches and backported patches only. Send new patches to libc-alpha)
• libc-help (Need help? Any glibc question is a valid question on this list)

6.2. Generate patch

Use git format-patch to generate your patch from your local commit

• Automatically generates numbered patches e.g.

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

• Use --to to identify the mailing list to send to, or any reviewer.

• Use --reroll-count to identify the version.

  • [PATCH vN 0/25] <Subsystem>: <Short description>

• Use --cc to identify anyone to CC.

• Use --subject-prefix to create a unique subject prefix. Specifically used for RFC, COMMITTED, or namespace patches.

  • Request for comment with no intent to apply the patch:

    • [RFC] <Short description>

  • A change to a non-master branch namespace:

    • [PATCH namespace/branch] <Subsystem>: <Short description>, e.g., [PATCH roland/arm-memcpy] ARM: Make multiarch memcpy always use NEON when compiler does

  • A patch that is already committed because it was obvious, or you are a subsystem maintainer and can assume consensus and commit patches.

    • [COMMITTED] <Subsystem>: <Short description>

Make sure that your commit is on top of a commit which is already in the public Git tree, so that your collaborators can apply it using git am -3.

You may then need to modify the email subject, or body accordingly.

6.3. Adjust the email body

You may need to adjust the patch to include notes that you don't want included in the commit.

• If you need to discuss something outside the patch do so at the beginning of the email and then use 8< or >8 (see man git-mailinfo) to indicate the end of the discussion and the start of the patch.

• If you are a new contributor please explain your current FSF copyright assignment status (see [[#FSFCopyrightAssignment|FSF copyright assignment).

Note: There is an advanced usage here using git-notes see man git-format-patch.

6.4. Email the patch

After adjusting the git format-patch file you will be in one of two situations:

• You can email the file directly (equivalent to inlining the patch).

  • See git send-email and git send-mail (requires configuring for your SMTP server).

• You can attach the file to an email that contains the same subject, to, cc, body and other email information.
  • 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").

Only one patch per email. Patchsets should be numbered (git format-patch will do this for you) and versioned to allow for committers to easily pull patches from patchwork and apply them in sequence for testing. Please do not attach more than one patch per email since patchwork does not support this. In general this follows the git send-email format.

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

7. Review

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

8. Commiting

Committers must review the committer checklist.