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:

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.

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.

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.

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.

     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

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:

Here a some examples of commit subjects:

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.

5.3. Attribution

The commit message body must also include attribution.

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:

6.2. Generate patch

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

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.

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:

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.

None: Contribution checklist (last edited 2020-08-22 17:04:16 by SiddheshPoyarekar)