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

[Jan Beulich <jbeulich@xxxxxxxx>]

On 13.11.2025 13:28, Andrew Cooper wrote:
> 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?

Well, ...

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

... this distinction isn't made clear (enough) for my taste. And while I agree
with "usually", there are the rare cases where qemu and/or minios tags would
still need making and propagating (the latter normally being done by me rather
than the release engineer).

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

In practice maybe, but not as per the original doc?

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

Why not? It's all part of the branching operation.

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

As far as changing what was written down so far goes, I'd certainly agree.
But as per the original branching-checklist.txt it's not spelled out either
way, so describing it one way or the other can be seen as part of the
re-write.

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

Yes, fine with me.

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

Oh, I see. The absence of *_UPSTREAM_REVISION made me not recognize it as
what it is.

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

Well, okay.

Jan