iproute/README

Iproute Package Management
==========================

This document describes how changes to the iproute2 RPM package are performed
by its maintainer and provides useful information for everyone who needs to
work on the iproute RPM package.

In the following, both contributors and maintainers workflow are described in
details, to make them as easy as possible to understand.  We define
"contributors" all the people contributing patches and backports to iproute2,
while we define "maintainers" all the people building the iproute2 RPM package
for Red Hat distros.

The current workflow is conceived to be as similar as possible to the kernel
one, so that kernel developers will ideally meet no barrier in contributing
backports to iproute.

Every task is performed on a Git repository containing the actual iproute2
sources.  A dedicated redhat/ directory contains the necessary files to prepare
a dist-git commit for a new release when desired.


Git repository structure
------------------------

The authoritative git repository for iproute2 RPM package is:

https://gitlab.cee.redhat.com/aclaudi/iproute2

There are several branches:
- 'devel' is the branch for package management changes.  It tracks latest
  upstream tagged version
- 'upstream' tracks iproute2 upstream stable repository
- 'upstream-next' tracks iproute2 upstream -next repository
- several other branches, named as the distro, followed by the distro version
  after an hypen.  E.g. 'rhel-7.3' is the relevant branch for RHEL-7.3 iproute
  package, while 'centos-9' is the branch for CentOS Stream 9.


Contributor Workflow
--------------------

Each contribution to the iproute2 package is expected to happen using a
GitLab merge request (MR).

Contributors can follow these general instructions on submitting an MR using
the GitLab UI[^1].  Kernel developers who are familiar with the
link:lab.adoc[lab] GitLab command line tool can use it to submit MRs.

Merge requests and individual commits are expected to follow some basic rules:
- Draft MR, i.e. MR not intended to be merged by the maintainer, should have a
  title prefixed with "Draft: "
- Every MR and commit must contain a "Signed-off-by: " line.
- Every MR and commit targeted at the package management files/scripts (e.g.
  addressing the redhat/ directory content) must be prefixed with '[redhat]' in
  the title.
- Every MR and commit must contain a 'Bugzilla:' line, with the exception of
  '[redhat]' ones.

Each MR will trigger an iproute2 CI pipeline. This will be described in detail
in the 'iproute2 package CI' paragraph.

[^1] https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html


Maintainer workflow
-------------------

The iproute2 package maintainers will take care of all the tasks related to the
creation of a working RPM package for Red Hat distros.  They also take care
about gating issues, bugzilla issues, errata, etc.

Maintainers perform the following tasks on the iproute2 RPM git repository:
- Create branches for each distro version;
- Check, review, approve and merge contributions;
- Review CI pipelines results, and fix it when needed;
- Rebasing the package to a new upstream version;
- Tag and build new package versions.

When creating a new branch, the maintainer ensure it uses the correct naming,
e.g. rhel-8.6, centos-9 or fedora-36.  Also, before pushing the new branch, the
maintainer should execute `cd redhat && make <distro>`; this ensure the proper
vars are used for the RPM package generation.

Before merging any contribution, the maintainer should check that MRs and
commits follow the guidelines outlined in the 'Contributor Workflow' section;
the maintainer should also check CI results are PASS.

Finally, to tag and build a new package version, the maintainer should use the
following command:

`cd redhat && make`

This command performs a series of operations detailed below in the 'How does cd
redhat && make works?' section, and ends printing the iproute dist-git repository
path in the /tmp directory.

The maintainer is expected to cd into this directory, look at the changes,
inspect the diff file, perform a test build, and generally to check everything
is fine with the package.  If this is the case, a new release can be finalized:

1) Commit the already added changes, using the 'changelog' file as commit
   message (it lists the BZ IDs as well, so the Git server hooks can validate if
   the changes are allowed or not).
2) Push the new commit.
3) Proceed with the regular release process, i.e. triggering a brew/koji build,
   updating the resolved BZ tickets and the errata.

To rebase the package to a new version, the BUILD variable in the distro.mk
file should be moved back to 1.  In this case the build process will ask for
the rebase bugzilla number, and will output a single-entry changelog detailing
the new version. All old patches will be removed and a new tarball will be
downloaded from upstream, ready for distro packager upload.


iproute2 package CI
-------------------

A minimal CI pipeline is included in the .gitlab-ci.yml file.  The purpose of
this pipeline is to perform some basic tests (e.g. build the source and the rpm
package) and ensure the code is ok to be released.  If the RPM package build
ends successfully, x86_64 packages will be stored as an artifact.

Contributors interested in testing changes not yet committed upstream can use a
"Draft" MR on the devel branch to trigger the pipeline and have an RPM package
built for them, ready to be tested by QE or anyone.

A nightly CI build rebases upstream and upstream-next branches to the latest
upstream, and builds an RPM package ready to be used by anyone for testing
purposes.


How does 'cd redhat && make' works?
-----------------------------------

Calling make inside the redhat/ subdirectory is the way produce a new iproute2
release for a given distro, be it RHEL, Fedora or CentOS.  Obviously, the
correct distro packager should be installed to make this possible (i.e. rhpkg,
fedpkg or centpkg), and the user should have a valid kerberos ticket.

This is what happens when make is called:

1) Release preparations are performed:
 a) Incrementing the BUILD variable in redhat/distro.mk
 b) Copying the specfile template to redhat/rpm/SOURCES/iproute.spec and
    updating it's changelog (basically a list of subjects, but with BZ ID
    added).
 c) Copying redhat/rpm/SOURCES/iproute.spec to redhat/rpm/SPECS/
 d) Copying additional files to redhat/rpm/SOURCES/
 e) Fetching the updated changelog back from redhat/rpm/SPECS/iproute.spec to
    the template file

2) A new release is created, which includes:
 a) Committing the updated redhat/distro.mk and redhat/iproute.spec.template as
    the final release commit
 b) Finally, an annotated tag is created. This will serve as the base reference
    for the next release, e.g. when creating changelog entries.

3) The dist-git repository is cloned and prepared for committing:
 a) A config for customization of this step is read from redhat/distro.mk
 b) The relevant tree is cloned to a temporary directory
 c) The right branch is checked out
 d) Files from redhat/rpm/SOURCES/ are copied into the clone and added
 e) A diff is created for review (should be empty)
 f) A changelog file is created, which will serve as template for the upcoming
    commit's message

Finally, the process ends printing the path of the dist-git repository,
tipically in the /tmp directory.