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

[Jan Beulich <jbeulich@xxxxxxxx>]

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?

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?

> +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.

> +   ``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.

> + * Tag.  Produce tarballs.

Link to the respective section further down?

> +e.g. from Xen 4.20, ``5cd830509d38^..3ad5d648cda5``::
> +
> +  * 3ad5d648cda5 - (tag: RELEASE-4.20.0) Update to Xen 4.20
> +  * 89fd1ba88403 - Config.mk: Bump tags to final
> +  * 6bf05e086765 - SUPPORT.md: Define support lifetime
> +  * 5cd830509d38 - CHANGELOG.md: Set release date for 4.20
> +
> +
> +Tagging
> +=======

Likewise this section may want linking to from respective places above?

Jan