Skip to content

Revise release-related Git workflow

Michał Kępień requested to merge michal/revise-release-related-git-workflow into main

This MR mostly serves as a place to discuss proposed changes to BIND 9's release-related Git workflow and the corresponding release checklist updates. In practice, these changes should only affect QA processes and not SWENG in general, but anyone is welcome to chip in.

The current workflow for handling numbered releases is as follows:

(Some steps were omitted for simplicity.)

  1. When a numbered release is almost ready to be published, a documentation MR is created in the private repository (because we want to have the same process for security releases and regular maintenance releases).

  2. The documentation MR cleans up release notes by applying minor corrections, reordering release notes, etc. Those changes are applied to doc/notes/notes-current.rst.

  3. The last steps in the documentation MR are:

    • renaming doc/notes/notes-current.rst to doc/notes/notes-9.x.y.rst,

    • removing doc/notes/notes-current.rst from doc/arm/notes.rst.

  4. The documentation MR is merged into a release branch (v9_x_y-release), which also only exists in the private repository.

  5. The version number is bumped on the release branch and a CHANGES marker is added.

  6. A release tag is created from the tip of the release branch.

  7. The code freeze is lifted, life goes onMRs targeted at the next milestone are merged into the development branch (and backported to maintenance branches).

  8. After public release of the numbered version, a merge request is created out of its release branch. The branch is then rebased on top of its relevant development/maintenance branch (because we enforce semi-linear Git history via GitLab project settings) and merged.

  9. The cycle is restarted when the next version is ready to be published.

The issues with the current workflow are:

  • git describe does not really work because we are not merging back tags but rebased branches, so the "original" tags are not included in development/maintenance branches.

  • The BIND 9 version string reported by e.g. named -v may be confusing because it still shows the "old" release number until the release branch is merged back. And even then, the version string does not clearly discern between "numbered" and "interim" versions (apart from the Git commit hash).

  • Until release branches are merged back into development/maintenance branches, Read the Docs shows a mix of release notes for the "version about to be publicly released" and "the next version". (This has caused confusion more than once in the past.)

  • Rebasing the release branches may cause context to be lost long-term in the development/maintenance branches (e.g. some of the rebased commits may become empty; these commits generally contain different changes than the original commits on the release branch).

  • Rebasing the release branches requires focus (yes, this is corporate speak for "the process is error-prone") so that no "current" release note leaks into the long-term doc/notes/notes-9.x.y.rst files and that no "current" release note is removed from doc/notes/notes-current.rst.

New workflow

This MR proposes to use a revised workflow:

  1. When a numbered release is almost ready to be published, a documentation MR is created in the private repository (no change here).

  2. The first steps on the release branch are to rename doc/notes/notes-current.rst to doc/notes/notes-9.x.y.rst and to remove doc/notes/notes-current.rst from doc/arm/notes.rst (this is step 3 in the current workflow).

  3. Documentation tweaks are applied to doc/notes/notes-9.x.y.rst on the release branch (this is step 2 in the current workflow).

  4. The version number is bumped on the release branch and a CHANGES marker is added (this is step 5 in the current workflow).

  5. A release tag is created from the tip of the release branch (this is step 6 in the current workflow).

  6. The code freeze is lifted. A merge request resetting the release notes and updating the version number (including the -dev string) is prepared for each development/maintenance branch (this is new!).

  7. After public release, a merge request is created out of each release tag. Instead of rebasing the release branch, each release tag is non-linearly, manually merged into its relevant development/maintenance branch (via git merge --no-ff v9_x_y + git push origin main). The catch here is that the merge commit must reconcile the development/maintenance branch with the release branch, so that from the point of view of the former, all that the non-linear merge causes is the addition of doc/notes/notes-9.x.y.rst to the tree and updating doc/arm/notes.rst with that file. Note, however, that this can be done without much thinking:

    git checkout HEAD -- configure.ac doc/notes/notes-current.rst
sed -i "/notes-9.x.y.rst/i.. include:: ../notes/notes-current.rst" doc/arm/notes.rst
git add doc/arm/notes.rst
sed -i -E "/^(<<<<<<<|>>>>>>>)/d; s/^=======$//" CHANGES
git add CHANGES
git commit

  8. The cycle is restarted when the next version is ready to be published.

This has the following benefits compared to the current workflow:

  • git describe somewhat works. It still fails to work accurately for commit hashes before release tag merging, but we cannot fully work around that anyway unless we do all release work in the public project (which we cannot due to the nature of the ASN process) and the revised process is a net improvement (the "accuracy" becomes "± one minor release" instead of "± an arbitrary number of releases on the current development/maintenance branch).

  • The version string reported e.g. by named -v becomes unambiguous.

  • Read the Docs contents become unambiguous as the release notes should never be mixed between releases any more.

  • Release branches are retained in their original form in development/maintenance branches because no rebasing takes place.

  • Merging release branchestags back no longer requires a lot of care (some is still necessary ;-))

The catches with the revised workflow are:

  • We are stepping into "non-linear Git history" territory (just for release branches, though, so AFAICT this should not affect SWENG work much).

  • Merging tags without rebasing involves command-line work and a rather thorough understanding of the process. Fixing broken merge commits will require force-pushes to development/maintenance branches or follow-up MRs (though to be fair, the latter already happened for the current process a few times anyway...)

Other, minor changes to the release checklist that this MR proposes are a follow-up to the post-9.11-EoL cleanups which happened during BIND 9.19.0 release preparations:

  • Code freezes are to be enforced via GitLab repository settings rather than "advised". This should prevent accidental merges during code freeze (like !6113 (merged)).

  • Steps for adding CHANGES markers were moved around to better reflect the order in which they usually happen on release branches.

  • We no longer prepare release notes in text form. HTML & PDF forms should still be checked (they are included in the tarballs produced by release GitLab CI jobs), same as man pages (this requires building from the source tarball for BIND 9.16+, though).

Any questions? :-)

Edited by Petr Špaček

Merge request reports