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](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.

<!--
-- This documentation file is covered by the patch-git license:
--
-- patch-git, a patch management tooling for dist-git.
-- Copyright Red Hat, Inc.
--
-- This program is free software: you can redistribute it and/or modify
-- it under the terms of the GNU General Public License as published by
-- the Free Software Foundation, either version 3 of the License, or
-- (at your option) any later version.
--
-- This program is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
-->