Contribution checklist - glibc wiki (original) (raw)

Contents

1. Read first
2. Copyright and license
   1. Copyright FSF or disclaimer
   2. Developer Certificate of Origin
3. Patch development
   1. Security
   2. Locales
   3. Bugzilla entry
   4. Identify related changes
   5. Update copyright information
   6. Properly Formatted Changes
   7. Documentation
4. Testing
   1. Testing Locales
   2. Check For New Warnings
5. Commit formatting
   1. First line
   2. Commit message body
   3. Attribution
6. Emailing your patch
   1. Determine email recipient
   2. Generate patch
   3. Adjust the email body
   4. Adjust the email subject
   5. Email the patch
7. Review
   1. Patchwork CI/CD
   2. Ping and Keep Pinging
8. Commiting

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:

• 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.
• Review pre-commit CI in patchwork.
• Ping at least weekly if your patch has not been reviewed yet
• Work with developers to reach consensus on the patch, posting new versions as required to address comments
• 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.

If you are covered by an existing copyright assignment to the FSF, please do not add Signed-off-by: to your commit messages. We want to be able to clearly distinguish between commits where copyright is assigned and those where it is not. Thank you.

2.1. Copyright FSF or disclaimer

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

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 or a disclaimer then please follow this process: https://sourceware.org/glibc/wiki/CopyrightFSForDisclaim

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 <random@developer.example.org>

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.

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 making nontrivial changes that are contributed by assigning copyright to the FSF, affected files should contain an FSF copyright notice like the following (you can follow "Copyright" with " (C)" if you like):

  ... One line file description ... Copyright 2022 Free Software Foundation, Inc.

  ... rest of license notice ...

• If you are adding changes to a file, and the changes are contributed via a Developer Certificate of Origin rather than by assigning copyright to the FSF, the changes should add the following to the top of the file after the 1-line description:

  Copyright The GNU Toolchain Authors.

• The copyright notices of some files indicate 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 (depending on the license the contributor is contributing under). E.g.,

  Copyright (C) 2012-2013 Free Software Foundation, Inc. ... rest of the first license notice ...

  Copyright (C) 2010 other-copyright-holder ... rest of the second license notice ...

3.6. Properly Formatted Changes

Please see Style_and_Conventions for a full description of coding guidelines.

Please note that "Contributed by" statements are no longer required or desired in glibc source files. All previous "Contributed by" statements were moved to a top-level CONTRIBUTED-BY file.

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.
• Review the pre-commit CI/CD results on patchwork and work with the relevant pre-commit CI maintainers to pass those checks.

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@sourceware.org (Development list for glibc, any subsystem)
• libc-locales@sourceware.org (Locale subsystem change discussions only. Send new patches to libc-alpha)
• libc-stable@sourceware.org (Discussions around stable branches and backported patches only. Send new patches to libc-alpha)
• libc-help@sourceware.org (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:">
  • [PATCH 1/2] <Optional unique prefix e.g. "String cleanup:">
  • [PATCH 2/2] <Optional unique prefix e.g. "String cleanup:">
• Use --cover-letter to add a cover letter whose information you can fill in before emailing.
• Use --to to identify the mailing list to send to, or any reviewer.
• Use --reroll-count to identify the version.
  • [PATCH vN 0/25] :
• 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]
  • A change to a non-master branch namespace:
    * [PATCH namespace/branch] : , 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] :

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 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).
  • Use git send-email to do this; this is the preferred method since it does the right thing for patches and patch series. This requires you to configure git for your SMTP server; this StackOverflow answer has details on how to do that for GMail and those instructions should help you configure for standard SMTP servers too.
• 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 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:

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

8. Commiting

Committers must review the committer checklist.