TODO: Update according to modification/redesign of rpm.org

RPM Maintenance

Git branches

Rpm development takes place in the git master branch, but releases are created from stable branches, created when a development cycle is coming to an end. Alfa tarball is traditionally cut from master, but prior to beta release the tree is branched and beta and later releases are always created from a branch, not master.

  • rpm-4.15.x branch from which all 4.15.x versions are cut from
  • rpm-4.14.x branch from which all 4.14.x versions are cut from

When pulling fixes from git master to stable branches, always use -x to get the automatic cherry-pick commit marker. This way its easier to see which patches come from master, and which commit exactly. If a cherry-pick conflicts, see if it’s resolvable with a suitable upstream commit and if not, when fixing manually change the “cherry-picked from” message into “Backported from commit hash” to mark the difference.

Selecting commits for cherry-picking (or backporting) for maintenance updates

For each fix or other change you consider cherry-picking, ask yourself:

  • Does it change the ABI or API in an incompatible way?

    Generally adding entirely new APIs is okay, any other change is not, except of course to fix behavior bugs.

  • Does it affect package building in an incompatible way?

    For example, adding new types of requires within stable releases is not a good idea (but provides are mostly harmless). New spec sanity checks may seem obvious, but unless its a crasher, chances are somebody is actually (ab)using it and will be unhappy if the package no longer builds. New warnings are generally okay, hard errors often are not.

    As a rule of thumb: If a package was buildable with rpm-X.Y.Z then it should also be buildable without changes on rpm-X.Y.Z+1, even if it relies on buggy behavior.

  • Does it affect package installation in an incompatible way?

    Rpm is commonly used to install much older and also newer packages built with other versions than the running version, installation compatibility is hugely important always and even more so within stable branches.

    As a rule of thumb: If a package was installable with rpm-X.Y.Z then it should also be installable without changes on rpm-X.Y.Z+1, even if it relies on buggy behavior.

If the answer to any of the above is “yes” then its almost certainly not appropriate for stable maintenance release.

Cutting a release

  1. Prepare preliminary release notes at http://rpm.org/wiki/Releases/X.Y.Z

    • Not every commit needs a corresponding release notes entry, eg internal refactoring and cleanup should not be detailed, and often a new feature consists of multiple commits that deserve exactly on entry in the notes
    • Follow common style in the text, git commit messages are rarely good as-is. Start with what it does: add/fix/remove/change/optimize, followed by concise description. Group and sort by types of change.
    • Not all releases need the same exact subtitle groups, use common sense.
    • Upstream GH tickets can use #ticketno shortcut, references to external bugzillas follow naming conventions: RhBug:bugno, SuseBug:bugno, MgaBug:bugno (optimally make these actual links)
  2. Prepare the sources:

    • Bump the version in configure.ac
    • Bump rpm_version_info (ie library soname version info) in rpm.am. Basic libtool guidelines for maintenance updates to stable versions:
      • consult the libtool manual
      • soname bumps can only occur at the first version of a new branch (ie alpha/beta)
    • Optionally Update translations from Zanata (TODO: document)
    • Update the sources for the above (Makefiles, .po regeneration and all): make dist
    • Commit the changes from the previous step with something like ‘Preparing for X.Y.Z’ as message
  3. Generate the final release tarball:

    make distcheck

  4. Check that the previous step does not introduce any new changes (eg ‘git diff’)

  5. Unpack the tarball next to the previous version and inspect the differences (something like ‘diff -uNr rpm- rpm-<X.Y.Z+1>') and watch out for unexpected material. If you find any, STOP, figure it out and go back as many steps as required.

  6. Submit the whole lot as a pull-request to the branch in question

    • In case of maintenance releases, leave it up for commenting for at least a week to allow for community feedback
    • Review needs a different mindset than new code: look for compatibility and stability issues in particular, as per “selecting commits” above
  7. Tag the release. Something like:

    git tag -a -m “RPM X.Y.Z release” rpm-X.Y.Z-release

  8. Push the tag. This is the point of no return for a given release.

    git push –tags

  9. Upload the bz2 tarball
    • scp to rpm@ftp-osl.osuosl.org to the appropriate per-branch directory in ~/ftp/releases/
    • run ./trigger-rpm script in the rpm home directory to start mirror process
  10. Make the release official:

    • add tarball checksum and download location to the release notes
    • add a new item to http://rpm.org/wiki/News and http://rpm.org/timeline
    • send an announcement mail to rpm-announce@lists.rpm.org and rpm-maint@lists.rpm.org (and why not rpm-list@lists.rpm.org too)