Re: [PATCH] docs: Rewrite the Tagging and Branching checklist

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 13/11/2025 7:54 am, Jan Beulich wrote:
> On 12.11.2025 19:54, Andrew Cooper wrote:
>> There's a lot of stale information in the current checklists.  Merge the
>> documents and present the information in chronological order.  Provide real
>> examples from the tree rather than trying to be too prescriptive.
>>
>> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
> Hardly anything is being said about stable releases - is this intentional?

Is there anything you think I'm missing?

I suppose the releasing section is slightly specific to new releases,
but for the stable release, it really is just bump extraversion, commit
and tag, and where usually tag is the only action after you've prepared
the tree.

>
> A few comments below, but ultimately I think it will need to be Julien to
> ack.
>
>> --- /dev/null
>> +++ b/docs/process/tagging-branching.rst
>> @@ -0,0 +1,194 @@
>> +.. SPDX-License-Identifier: CC-BY-4.0
>> +
>> +===============================
>> +Tagging and Branching Checklist
>> +===============================
>> +
>> +Before starting
>> +===============
>> +
>> + * Review this checklist for changes during the development window.
>> + * Access to the following necessary:
>> +
>> +   * The 'xen tree' signing key.
>> +   * The xen and xendocs users on xenbits.xen.org
>> +   * The downloads-cvs user on mail.xenproject.org
>> +   * A checkout of the xen.org CVS repository
>> +
>> +::
>> +
>> +  cvs -d downloads-cvs@xxxxxxxxxxxxxxxxxxx:/home/downloads-cvs/cvs-repos 
>> checkout xen.org
>> +
>> +
>> +For RC1
>> +=======
>> +
>> + * Pin ``QEMU_UPSTREAM_REVISION`` to an exact SHA.  Commit.
>> +
>> + * Update ``XEN_EXTRAVERSION`` from ``-unstable`` to ``.0-rc1``.  For
>> +   ``README`` and ``SUPPORT.md``, use the slightly more generic ``-rc`` so
>> +   they doesn't need to change during subsequent RCs.  Commit.
> Nit: don't
>
>> + * Tag.  Produce tarballs.
>> +
>> +e.g. from Xen 4.21, ``ffd25d717a74^..d1478321eacb``::
>> +
>> +  * d1478321eacb - (tag: 4.21.0-rc1) Update Xen version to 4.21.0-rc1
>> +  * ffd25d717a74 - Config.mk: Pin QEMU_UPSTREAM_REVISION
>> +
>> +
>> +For subsequent RCs
>> +==================
>> +
>> + * Update ``XEN_EXTRAVERSION`` to the next RC number.  Commit.  Tag.
>> +
>> +e.g. from Xen 4.21, ``eff32008be0d`` and ``9632ce6fe5b2``::
>> +
>> +  * 9632ce6fe5b2 - (tag: 4.21.0-rc3) Update Xen version to 4.21.0-rc3
>> +  * eff32008be0d - (tag: 4.21.0-rc2) Update Xen version to 4.21.0-rc2
>> +
>> +
>> +Branching
>> +=========
>> +
>> +On xenbits:
>> +
>> + * Create new staging and stable branches in xen.git.
>> +
>> + * Add the new branches to patchbot.  In ``~xen/HG/patchbot`` copy the 
>> exsting
>> +   master and staging reported heads, update the ``versions`` file, and 
>> commit
>> +   the result.
>> +
>> + * Add the new stable branch to the docs cronjob.  In ``~xendocs/cronjobs``
>> +   edit ``xenbits-docs-all.sh`` and commit the result.  e.g.:
>> +
>> +::
>> +
>> +  ssh xenbits.xen.org
>> +
>> +  cd ~xen/git/xen.git
>> +  git branch staging-$v staging
>> +  git branch stable-$v master
>> +
>> +  cd ~xen/HG/patchbot
>> +  cp xen--master.patchbot-reported-heads 
>> xen--stable-$v.patchbot-reported-heads
>> +  cp xen--staging.patchbot-reported-heads 
>> xen--staging-$v.patchbot-reported-heads
>> +  $EDITOR versions
>> +  git commit -am "Branch for $v"
>> +
>> +  cd ~xendocs/cronjobs
>> +  $EDITOR xenbits-docs-all.sh
>> +  git commit -am "Branch for $v"
>> +
>> +
>> +On the new branch:
>> +
>> + * Switch to release builds by default.  Commit.
>> +
>> +On staging:
>> +
>> + * Update ``XEN_SUBVERSION`` to the next version.  Update
>> +   ``XEN_EXTRAVERSION``, ``README`` and ``SUPPORT.md`` back to 
>> ``-unstable``.
>> +   Commit.  Tag the start of the new development window.
>> +
>> + * Rerun ``./autogen.sh`` to refresh the configure scripts.  Commit.
>> +
>> + * Switch ``QEMU_UPSTREAM_REVISION`` back to ``master``.  Commit.
>> +
>> + * Create a new section in ``CHANGELOG.md``.  Commit.
> Should this really be four separate commits?

It is and has been for a while.

Folding autogen into the version update might be sensible.  Everywhere
else needing an autogen does so in the same patch.

But, I don't see it being sensible to fold the remaining thee patches.

This also begs the question of how we indicate a planned change from the
example given.  Maybe "Note, example is from prior to deciding to $X",
which gets removed when the example gets updated?

If we're going to do that, I'd want to make it a separate change to the
main rewrite.

>
>> +e.g. from Xen 4.21, ``d510f9c1430c^..62d0a92057ca`` and 
>> ``d510f9c1430c^..b0255656d121``::
>> +
>> +  * 62d0a92057ca - CHANGELOG.md: Start a new 4.22 section
>> +  * 7b88e463f999 - Config.mk: Switch QEMU back to master
>> +  * d954e8c5c8de - Rerun ./autogen.sh for 4.22
>> +  * 85768c28b705 - (tag: 4.22-dev) Update Xen to 4.22
>> +  | * b0255656d121 - (staging-4.21) Switch to release builds by default
>> +  |/
>> +  * d510f9c1430c - doc/man: Align list of viridian default enlightenments 
>> with libxl
>> +
>> +
>> +Releasing
>> +=========
>> +
>> + * Finalise the release dates in ``CHANGELOG.md`` (backported from staging)
>> +   and ``SUPPORT.md`` (only in the release branch).
>> +
>> + * Tag the release in relevant external repos, and update ``Config.mk`` to
>> +   refer to the tag.
>> +
>> + * Update ``XEN_EXTRAVERSION`` to drop the ``-rc`` suffix, and update
> Since further up it's now rc<N>, imo it would be better to also say it that 
> way
> here.

One thing I found very problematic with the older checklists was the
excessive use of variables.  In this doc, I've got it down to two, and
using the examples to clear up any ambiguity.

Would "to drop the RC suffix" work?  This is supposed to be clear that
it means rc and whatever number we've got to, but rc<N> (especially
rendered as a literal) doesn't help IMO.

>
>> +   ``README`` to match.  Commit.
> The latest here QEMU_UPSTREAM_REVISION and MINIOS_UPSTREAM_REVISION also need
> adjusting to reference version tags, aiui. Taking tag creation in the 
> respective
> leaf trees as prereq.

That's the previous bullet point.  I should probably make it clearer
saying ``*_UPSTREAM_REVISION`` but naming more specifically like that is
going to bitrot.

>
>> + * Tag.  Produce tarballs.
> Link to the respective section further down?

I considered that.  The linking syntax detracts from the readability as
a text file, while on the rendered version it's clear from the
navigation panel that there are relevant sections.

~Andrew