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

The following describes how changes to the iproute package are performed by
it's maintainer. This documentation is necessary as the process has changed
for RHEL7.3 and is not obviously comprehensible anymore just by looking at the
rhpkg Git history.


How The Old Process Looked Like
-------------------------------

Previously, all changes were delivered in form of patches applied on top of the
vanilla release from upstream. The SRPM would contain all patches, and at build
time fetch the release tarball from upstream and apply the patches in order.

This approach has drawbacks when the number of backported changes increases:
Either several backported patches are combined into a single patch file which
makes it harder to keep track of already backported changes or each upstream
commit is dedicated it's own patch file which increases the spec file and build
overhead.

In addition to the above, in order to perform clean backports, one has to first
"recover" a real Git repository from the base release and all the patches.


Anatomy Of The New Process
--------------------------

The kernel package development process served as a blueprint for the changes:
Everything evolves around a Git repository containing the actual iproute2
sources. A dedicated redhat/ directory contains the necessary files to prepare a
new rhpkg commit for a new release when desired.


Backporting A Commit From Upstream
----------------------------------

The repository to backport commits to resides at:

git://git.engineering.redhat.com/users/psutter/iproute2.git

For RHEL7.3, the branch named 'rhel7.3' is the relevant one.

Some important things regarding the commit message:

- Internal commits (e.g. ones addressing the redhat/ directory content) should
  be prefixed '[redhat]' in their subject line, so they are excluded from the
  changelog.
- Every non-internal commit has to contain a 'Bugzilla:' line. It's content is
  used when creating the spec changelog and rhpkg commit message.


Creating A New Release
----------------------

To publish the current state in a new release, simply calling 'make' inside the
redhat/ subdirectory should suffice. Worth noting, this should be run on a
system with 'rhpkg' available and working Kerberos setup. This is what happens:

1) Release preparations are performed:
 a) Incrementing the BUILD variable in redhat/rules.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 (avpkt, cbq-0000.example) 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/rules.mk and redhat/iproute.spec.template as
    the final release commit
 b) Using 'git-archive', sources are packed into a tarball and saved in redhat/
    as well as redhat/rpm/SOURCES/ directories.
 c) 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/rhpkg.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) The previously created tarball is uploaded and the 'sources' and
    '.gitignore' files updated accordingly
 f) A diff is created for review (should be empty)
 g) A changelog file is created, which will serve as template for the upcoming
    commit's message

After looking at the temporary clone's changes, inspecting the diff file, doing
a test build, etc. it is time to finalize the new release:

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 build,
   updating the resolved BZ tickets and the errata.
