Commit Rules

In addition to the requirements in section 1, z-stream Merge Request titles should be appended with the targeted z-stream name in square brackets. For example,

Additional metadata, such as the Jira ID or CVE ID, should be included in the Merge Request description and not the title.

Each commit in a changeset and the MR description must reference at least one Red Hat Jira URL on a line beginning with “JIRA: https://issues.redhat.com/browse/RHEL-<ID>” (where <ID> is a valid number). If the MR resolves multiple jiras, the description must include only one jira URL per “JIRA:” line. Jira IDs (ie, just a tag & number) are not acceptable.

Changesets that are lacking a Jira will not be committed and will be immediately flagged by the project’s webhooks. Every changeset needs to be coordinated with other groups at Red Hat(management, QE, Documentation, etc.) and the coordination is handled through Jira fields and state.

The INTERNAL keyword can be substituted for a Jira URL. The INTERNAL keyword indicates a change to code that is considered to have minimal customer impact such as changes to files in the redhat directory (excluding CONFIG* files) or the .gitlab-ci.yaml file.

Good examples for Jira URLS in the description:

The comments of the Jira must include details on how the changes were tested.

If the upstream source tree is not linux.git, the description must include a URL, a git:// address, or a git+ssh address for the upstream source tree. Commits with an identified source must also specify a commit sha1 in their description.

If the changeset is not in Linus' linux.git tree, please specify the URL of the source tree, a URL to the patch posting on a mailing list, or explain why the changeset is unique to RHEL.

Non-upstream change tracking is useful for Engineering teams monitoring current, future, and update releases, therefore changesets that are not in an upstream tree and are unique to RHEL must have upstream status in the format "RHELX.Y.Z only". "RHEL only" must be used for changesets that must be applied to future versions of RHEL. Changes that will only be applied to a specific major release must have status "RHELX only", and changesets in a minor release that are temporary workarounds must be specified in the format "RHELX.Y only". Temporary workaround changesets can also include additional information about future work in parenthesis. Unique z-stream fixes must be specified with upstream status as "RHELX.Y.Z only". This follows the Tag Format described above, making "RHEL-Only" and similar forms acceptable, too.

Changes that have been sent upstream but have not been included in an upstream repo must have status “Posted” followed by a link to the upstream post, merge request, or pull request.

Critical undisclosed information security issues, or unreleased critical CVEs, may also use "Upstream Status: Embargoed".

Good examples of Upstream Status for changesets that are not in Linus’ linux.git:

Red Hat’s automated tooling attempts to do basic validation of upstream git tree references, currently accepting URLs starting with:

If the changeset resolves a Jira that has an associated CVE number, each commit in the changeset and the MR description must include the CVE reference ID. Use one “CVE:” line for each CVE that the changeset resolves, and include the number as described in the Jira, e.g "CVE-YYYY-XXXXX".

Unreleased critical CVEs can use "Upstream Status: Embargoed" in place of referencing an upstream commit ID.

If the commit differs from the original upstream commit, a short description of the differences should be included on a line that begins with “Conflicts:”. Simple patch conflicts like fuzz do not need to be documented.

If your changeset depends on another changeset being accepted and merged first, then you need to make sure that the description of your MR contains a reference to the dependent change.

For each dependency, your description must contain a unique line starting with Depends:. The content after the keyword should be a specific URL pointing at another MR in the same project.

When assembling the commits on your dependent changeset, you must make sure that the changes for your MR are layered over the dependent changes as displayed in the graphic below. Dependencies, as the name implies, must precede all changes from the submitted set. The webhooks rely on ordering to identify the last commit that is part of your changeset and the first commit of a dependency chagneset, and will stop walking the commit list when reaching the first dependency commit. Dependencies intermingled with your changes will not be properly evaluated by the webhooks.

In the event of a conflicting change from either the parent repository or the upstream (aka origin) repository, you will need to make sure to rebase your changes in order from eldest to youngest. For example, in the above graphics, a new commit was added to the upstream repository (commit 1d1d6d). You will need to make sure that Dependent Change 1 (aka parent) is rebased on origin, and then you can rebase Dependent Change 2 (aka child) on Dependent Change 1 (aka parent). This pattern needs to be repeated for every level of dependency in the chain.

If there is a subsequent upstream commit with any reference to the backported commit which is not included in the changeset it should be included on a line that begins with "Omitted-fix:". The "Omitted-fix:" line should include a minimum 12-character commit ID and the title of the omitted fix. The following line(s) must include a reason for omitting the fix.

The use of the "Omitted-Fix:" tag does not imply the decision to omit the fix is correct. The usage of the tag only means the author has chosen to omit that particular fix from their changeset. Reviewers must take care to confirm the decision to omit these commits is correct.

Good examples of omitted fixes:

Z-Stream uses couple additional tags that help track extra metadata for each commit. These tags are optional and if not present z-stream maintainers will typically attach these to commits via git-notes.

Red Hat follows an “upstream-first” philosophy, so commits with an Upstream Status that identify them as originating from an external tree must specify the git sha1 ID. Red Hat Kernel project’s tools parse the commit sha1 for analysis, so the format of the git sha1 ID is strictly enforced.

The upstream sha1 ID must be referenced using one of these three formats (pick one that suits better your workflow):

commit <full sha1 hash>
commit <full sha1 hash> (<branch name>)
(cherry picked from commit <full sha1 hash>)

The commit line starts at the first column (no whitespace at front is allowed) and is followed by a new line. To be precise, the following Perl regex must be able to match:

Upstream contributors Cc’s, Signed-off-by:, and other tags must be shifted right by 4 spaces to avoid the email bridge erroneously cc’ing non-redhat.com email addresses.