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.

The glibc project is licensed under the GNU Lesser General Public License v2.1 or any later version as published by the Free Software Foundation.

The project accepts patches with or without assignment of copyright to the FSF, but some conditions apply.

Some files in glibc are shared with other projects which do require copyright assignment to the FSF.

Please review the shared source files list and if the files you have altered are in that list then please discuss this with the reviewers when you post your patch. The project is in the process of reviewing shared source files and determining their status. Depending on the final status of the file you may or may not need copyright assignment.

If you need copyright assignment please follow this process: https://sourceware.org/glibc/wiki/CopyrightFSF

2.2. Developer Certificate of Origin

The glibc project allows contributions to use the "Sign-off" procedure originally introduced by the Linux Kernel project, and subsequently adopted by many other free software projects including GCC.

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a free software patch. The rules are pretty simple: if you can certify the below:

Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.

then you just add a line saying:

using your real name (sorry, no pseudonyms or anonymous contributions.) This will be done for you automatically if you use git commit -s.

Some people also put extra optional tags at the end. The glibc project does not require tags from anyone other than the original author of the patch, but other people involved in passing along the patch can add their own Signed-off-by if they wish.

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 The GNU Toolchain Authors.

     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. Adjust the email subject

The glibc project has recently started doing CI/CD testing via patchwork.

Patchwork understands 3 kinds of emails: Cover letter, Patch, comment.

In order for an in-reply-to with a new version of the patch to be treated as a new patch you must remove the "Re:" from the subject. If you leave the "Re:" then patchwork considers your reply a comment to the original patch. This is important to support reviewers using patchwork for pulling patches and for CI/CD systems testing your patches.

6.5. 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 are sending a new version, please reply to the original version of the patch via --in-reply-to=, this helps chain all the versions of the patch and supports developers using b4.

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

7. Review

7.1. Patchwork CI/CD

You can review your patch in the queue here: https://patchwork.sourceware.org/project/glibc/list/

Any Reviewed-by, Tested-by, or CI/CD success, warnings, or failures are all aggregated in patchwork.

The project by default is running two trybots:

7.2. 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 2021-09-24 15:22:16 by CarlosODonell)