glibc/CONTRIBUTING.md

Ticket references

All commits to this repository must reference a RHEL Jira ticket. To obtain a ticket reference, login to issues.redhat.com and create an issue of the appropriate type:

• Bug for defect fixes (bugs).
• Story for enhancements (new featurees).

For the component, choose glibc. After filing the ticket, leave it in status New, so that it can be reviewed in due course by the glibc team at Red Hat.

Please use publicly viewable ticket (keeping Security Level unset) for public contributions.

Reviews in Gitlab

Once the pipeline run is authorized and completed, automation will approve your merge request. This automated approval does not count. You must wait for human approval from a Red Hat Platform Tools team member. Once you have obtained review, you may merge.

Note that for the c10s branch, the pipeline is currently not green. On the c8s and c9s branches, it is green and should remain so.

Building locally

It is recommend to use the mock tool to build in a clean build environment. Use centpkg srpm to create the source RPM.

If you want to build locally, be aware that the patch-git tooling picks up additional patches in the $HOME/rpmbuild directory hierarchy. You can avoid this by building directly out of dist-git, without installing the source RPM using rpm -i first:

rpmbuild -bb -D "_sourcedir $PWD" glibc.spec

Trailers in Git commit messages

The patch management tooling (in patch-git.lua) assumes that all Git commit messages in this repository have a trailer. The trailer must be separated from the message body by a blank line. See git-interpret-trailers for the format details.

A Resolves: or Related: tag is required to be present in the trailer. Incorrectly formatted Git commit messages will lead to build failures. Running centpkg srpm locally is sufficient for performing the format checks.

For tags that accept boolean values, yes/no, true/false, 1/0 are recognized.

The following Key: value pairs are recognized.

• Resolves, Related. Contains a list of ticket references. Each reference must end in a digit (for example, RHEL-111490, swbz#567). Multiple references may be separated by spaces or commas. Do not repeat the same reference twice. Example:

  Resolves: RHEL-110535, RHEL-110949
  

  One of these tags must be present in every commit. The patch management tooling treats both tags as equivalent.

• Parent. The 40-character hash of the parent commit. Required when using RPM-Release or RPM-Changelog-Stop. Building fails if the commit hash in Parent does not match the actual parent commit. Example:

  Parent: 46a31fdf250a30ae96c082376a8eab95252762c0
  

  The Parent tag serves as a rebase protection mechanism. This protection is desirable when other tags in the same trailer trigger changes that could potentially hide information that was merged since the commit was created originally, against a different project history. For example, RPM-Changelog-Stop: yes stops processing further changelog entries. If a commit with this trailer gets rebased, previous RPM changelog entries might get lost because they previously were only reflected in the auto-generated %changelog part. Similarly, when setting the RPM release with RPM-Release, after an adjusted rebase, the release number may go backwards. The parent commit check serves as a reminder that before merging the rebased commit, manual checks are needed that history is not incorrectly overwritten.

• RPM-Branch-Type. Must be zstream if present. Switches to z-stream release numbering if that mode is not already active, by appending .1 to the release. (Future versions may add support for additional branch types like hotfix.)

• RPM-Skip-Release. Boolean. When yes, the release number is not incremented and no new changelog header is created for that commit.

• RPM-Changelog. Optional explicit changelog content. Use - on its own to indicate no entries. For multiple entries, indent continuation lines and prefix items with - . Example:

  RPM-Changelog:
   - Fix memory leak in fdopen (bug 31840)
   - libio: Test for fdopen memory leak without SEEK_END
  

  If there are no - lines, the changelog entry is automatically word-wrapped. If - lines are used, the line breaks found in the trailer are preserved in the RPM %changelog section.

• RPM-Changelog-Stop. Boolean. When yes, generation of changelog entries stops at this commit. Requires Parent.

• RPM-Version. Explict RPM version string. Must be a single word. RPM macros are not permitted (no %). Requires Parent. If the RPM version is not specified in a commit, it remains the same as in its parent commit.

• RPM-Release. Explicit RPM release string. Must be a single word that contains %{?dist}, includes at least one digit, and does not contain - or additional RPM macros. Requires Parent.

  If RPM-Branch-Type: zstream is present along with RPM-Release, the specified release is assumed to be a z-stream release. As a result, a subsequent RPM-Branch-Type: zstream tag will not add .1 at the end of the release, but increment the release as usual.

  If RPM-Release is omitted, the RPM release is generated from the parent commit, by incrementing the left-most number in its release string. (Special case: branch switching, as described above under RPM-Branch-Type.)

• Patch-Git-Version. Number with the patch-git format revision. This is only required on the oldest commit, which also has to specify Parent, RPM-Version, RPM-Release, RPM-Changelog-Stop. Later commits inherit the patch-git version from their parent commits. Example:

  Parent: 92dfd986b2f2c697144be2ebe10a27d72c660ba4
  Patch-Git-Version: 1
  RPM-Version: 2.39
  RPM-Release: 60%{?dist}
  RPM-Changelog-Stop: yes
  

  Currently, only version 1 is supported.

The patch-git tool can also be run directly, via patch-git.lua. These subcommands are particilarly useful:

• patches --history-only: Shows the patch files in application order, as computed from the Git history.

• verrel: Displays the version-release, as computed from the Git history.

• changelog: Outputs the auto-generated part of the RPM changelog. Use changelog HEAD^ to show the changelog entry for the most recent commit only.

Patch file contents

The *.patch files should use git show output if they are based on an identifiable upstream commit (which is very much preferred). If the patch is not equivalent to upstream, a comment should explain this before the commit line, otherwise the patch file should start with this line.

Further comments about the backport can be added after the upstream commit message (which is indented by four spaces, ). In this section, the line Conflicts: starts a special section of identified (semantic or textual) conflicts that could not be resolved by Git's merge tooling. Each line starts with a tab character. Each conflict resolution statement starts with one or more file lines (tab-indented, no further indent), followed by tab-and-space indented comments on the conflict resolution applied.

Licensing

Contributions should be upstream backports, following the upstream project's licensing conventions. Downstream-specific contributions (such as RPM spec file updates) follow the existing licenses of the files being changed. Otherwise, please specify the licensing conditions explicitly.

If not otherwise indicated in the source file, Red Hat's original contributions to this repository are licensed under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.