- Read first
- Copyright and license
- Patch development
- Commit formatting
- Emailing your patch
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 email@example.com.
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:
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 --firstname.lastname@example.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. Copyright and license
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.
2.1. Copyright FSF
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:
Signed-off-by: Random J Developer <email@example.com>
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
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.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").
- If you are adding a change to a file and those changes do not have their copyright assigned to the FSF (contribution via DCO), those changes should add the following to the top of the file after the 1-line description:
Copyright The GNU Toolchain Authors.
- 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).
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/
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.
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:
firstname.lastname@example.org (Development list for glibc, any subsystem)
email@example.com (Locale subsystem change discussions only. Send new patches to libc-alpha)
firstname.lastname@example.org (Discussions around stable branches and backported patches only. Send new patches to libc-alpha)
email@example.com (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>
- Request for comment with no intent to apply the patch:
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. 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:
- 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 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 firstname.lastname@example.org.
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:
- Does your patch apply?
- Does it successfully build on i686?
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.
Committers must review the committer checklist.