# Ticket references All commits to this repository must reference a RHEL Jira ticket. To obtain a ticket reference, login to [issues.redhat.com](https://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](https://git-scm.com/docs/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.