More intuitive branch names for documentation versions on Read the Docs ?

[unman]

Issue #10251 relates to branch names for documentation versions on Read the Docs

I'd like to bring this to a close with agreement.

The default names on RTD are "latest" to track main branch, and
"stable" to track the highest versioned branch.

There are arguments in favour of changing this. For what it's worth,
most RTD projects seem to use the default; Fedora uses "latest" for
the most recent release; Debian uses "stable" for the most recent
release, (and "oldstable" for the one before.)

These projects do not seem to see any issue with using these names in
their documentation, instead of URLS that point to specific releases,
(although they may support that also).

I do not know if it's possible to change the default namings in RTD to
keep the automatic updating. The documentation isnt particularly clear
on this, and (ironically) the documentation on building a working local
RTD on Debian is woeful.

It IS possible to change the default view to show documentation for the
stable branch. We should do this, under whatever name is chosen.

I think we need to establish:
1. Is it possible to change the default names - latest and stable?
2. If so, what names should we use?
3. If we do, is it possible to retain automatic generation of docs for
the most recent versioned branch?
4. If we do change from defaults, and it is not possible to retain
automatic generation, can we manually set our choice to point to the
most recent versioned branch?

2 is for general discussion.
1,3,4 need input from folk familiar with RTD.

unman

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Oct 10, 2025 at 01:16:16PM +0100, 'unman' via qubes-devel wrote:
> Issue #10251 relates to branch names for documentation versions on Read the Docs
>
> I'd like to bring this to a close with agreement.
>
> The default names on RTD are "latest" to track main branch, and
> "stable" to track the highest versioned branch.
>
> There are arguments in favour of changing this. For what it's worth,
> most RTD projects seem to use the default; Fedora uses "latest" for
> the most recent release; Debian uses "stable" for the most recent
> release, (and "oldstable" for the one before.)
>
> These projects do not seem to see any issue with using these names in
> their documentation, instead of URLS that point to specific releases,
> (although they may support that also).
>
> I do not know if it's possible to change the default namings in RTD to
> keep the automatic updating. The documentation isnt particularly clear
> on this, and (ironically) the documentation on building a working local
> RTD on Debian is woeful.
>
> It IS possible to change the default view to show documentation for the
> stable branch. We should do this, under whatever name is chosen.
>
> I think we need to establish:
> 1. Is it possible to change the default names - latest and stable?

In practice we can choose any names. The automatically updated "stable"
name is I think hardcoded, but IMO we don't need to use this mechanism -
it's not much work to switch branch every 2 years or so when new qubes
version gets released.

> 2. If so, what names should we use?

This is a very good question. To recap the issue, we have the following
proposals:
1. "latest" for development version, "stable" for most recent stable
version, "4.2" etc for older versions
2. "testing" for development version, "latest" for most recent stable
version, "4.2" etc for older versions
3. always use specific version like "4.2", "4.3"
4. some mix of the above

Unfortunately, version aliases seems to be not implemented yet
(https://github.com/readthedocs/readthedocs.org/issues/5318), so one
branch can have only a single version (it's impossible to have 4.2
visible as both "4.2" and "stable" at the same time).

Personally, I like 1 or 2. And include which version that actually is in
the documentation title (or somewhere else that is always visible).

> 3. If we do, is it possible to retain automatic generation of docs for
> the most recent versioned branch?

It's possible to add automation rules to set default version:
https://docs.readthedocs.io/page/guides/automation-rules.html

But as said above, we don't do new Qubes OS releases that often, it's
IMO okay to simply switch default manually as part of release checklist.

> 4. If we do change from defaults, and it is not possible to retain
> automatic generation, can we manually set our choice to point to the
> most recent versioned branch?

We can set any mapping branch -> version.

> 2 is for general discussion.
> 1,3,4 need input from folk familiar with RTD.
>
> unman

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmjpAHAACgkQ24/THMrX
1ywHFwf+MTKpFZfK4h+cUfHsBPIBwI7aFBzg6H3J2kAAHtJRX9cJcqvWcYVScOtc
qMLH08tYFTq5peyRFz3WYaan3raGHAbBX2C0EGc47vzuSFuh/ukMgATMHxwBVMqg
1iM8dzRG2MXqU8o9kb228+8/mDWnUuCTCJWPeIZcIzTQGoiWcXDxO8hOD0oH0DDX
eKvsu7OI0dVAHF+n0bou9bFNdCa+26pn2xVFgltow0j20E91M8WoxU2nu4baOE/P
7hbAAPdS7R6sM7TSvlE97yPjbHBtsSieVfz8GrvDcWaXGVB/5PGm5ACTYgV6kDlI
bvQGic8JZ6SKye6k5Jlo5r43shO05w==
=8wX1
-----END PGP SIGNATURE-----

[unman]

I agree that a manual change would not be great effort, if the automatic
system can be turned off.

.
>
> > 2. If so, what names should we use?
>
> This is a very good question. To recap the issue, we have the following
> proposals:
> 1. "latest" for development version, "stable" for most recent stable
> version, "4.2" etc for older versions
> 2. "testing" for development version, "latest" for most recent stable
> version, "4.2" etc for older versions
> 3. always use specific version like "4.2", "4.3"
> 4. some mix of the above
>
> Unfortunately, version aliases seems to be not implemented yet
> (https://github.com/readthedocs/readthedocs.org/issues/5318), so one
> branch can have only a single version (it's impossible to have 4.2
> visible as both "4.2" and "stable" at the same time).
>
> Personally, I like 1 or 2. And include which version that actually is in
> the documentation title (or somewhere else that is always visible).

There is also:
5. "testing" and "stable"
(if that is not subsumed under your 4.
This is the one I favor.

>
> > 3. If we do, is it possible to retain automatic generation of docs for
> > the most recent versioned branch?
>
> It's possible to add automation rules to set default version:
> https://docs.readthedocs.io/page/guides/automation-rules.html
>
> But as said above, we don't do new Qubes OS releases that often, it's
> IMO okay to simply switch default manually as part of release checklist.

Agreed.

>
> > 4. If we do change from defaults, and it is not possible to retain
> > automatic generation, can we manually set our choice to point to the
> > most recent versioned branch?
>
> We can set any mapping branch -> version.

OK

Thanks for input.

[parulin]

It would be really great to end up with a decision before the release of
Qubes R4.3, in order to have the two versions during the transition phase.

Could the "testing/stable" proposal of unman be a compromise?

On 10/11/25 06:38, 'unman' via qubes-devel wrote:
> There is also:
> 5. "testing" and "stable"
> (if that is not subsumed under your 4.
> This is the one I favor.

If not, using "latest/stable" would be less confusing than
"testing/latest". But anyway, even that last solution is better than the
current state of the docs (only one branch called "latest").

[tokidev]

Am 13.12.25 um 19:34 schrieb 'parulin' via qubes-devel:

> It would be really great to end up with a decision before the release of
> Qubes R4.3, in order to have the two versions during the transition phase.

Thank you for the reminder!

> Could the "testing/stable" proposal of unman be a compromise?
>
> On 10/11/25 06:38, 'unman' via qubes-devel wrote:
>> There is also:
>> 5. "testing" and "stable"
>> (if that is not subsumed under your 4.
>> This is the one I favor.
> If not, using "latest/stable" would be less confusing than "testing/
> latest". But anyway, even that last solution is better than the current
> state of the docs (only one branch called "latest").
>

What about "latest_testing" for the latest testing release and
"latest_stable" for the latest stable release? Older versions with "4.1"
etc.?

Best regards,
tokidev

[parulin]

So, recently the available versions changed, we now have 3 versions:

* latest
* r4.3 (default)
* r4.2

The idea of using "testing", "latest" or "latest_testing" and "stable"
has been abandoned?

[unman]

Yes. This is clearer and in accordance with naming convention elsewhere.
r4.3 is now the default view in RTD. (I still do not like "latest" but
that's a personal matter of little import.)
"latest" and r4.3 will run closely together for some time, but as work
continues to r4.4 or, indeed r5.0, there will be divergence. It would be
useful if developers could explicitly point out cases where work will not
impact r4.3.

[parulin]

On 2/28/26 05:38, 'unman' via qubes-devel wrote:
> Yes. This is clearer and in accordance with naming convention elsewhere.
> r4.3 is now the default view in RTD. (I still do not like "latest" but
> that's a personal matter of little import.)
> "latest" and r4.3 will run closely together for some time, but as work
> continues to r4.4 or, indeed r5.0, there will be divergence. It would be
> useful if developers could explicitly point out cases where work will not
> impact r4.3.

Ok, but right now, if I want to copy-paste a link, I don't have a good
solution:

* If using the default, the /r4.3/ part might become outdated or, worse,
removed.
* If I use the "latest" version, I might provide a link that contains
information about the next release.

The last situation is not so bad, but I thought that we would have had
some kind of "stable" version (and URL), which would have been the
default one...

[unman]

I do not understand how you think things have changed in this respect? As
soon as we adopted different branches for releases, this issue would
arise **regardless** of the naming scheme.

The r4.3 branch will not be removed.

--
I never presume to speak for the Qubes team.
When I comment in the mailing lists I speak for myself.

[parulin]

On 2/28/26 21:59, 'unman' via qubes-devel wrote:
> I do not understand how you think things have changed in this respect? As
> soon as we adopted different branches for releases, this issue would
> arise **regardless** of the naming scheme.

I'm talking about the URL scheme: having a default URL with
.../stable/... always pointing to the latest stable release would have
helped to keep links up-to-date. Anyway, the current solution is not the
one that you, Marek and others were in favor of, so I don't understand
the decision.

> The r4.3 branch will not be removed.

That's nice to hear.

[unman]

On Sun, Mar 01, 2026 at 04:52:47AM -0500, 'parulin' via qubes-devel wrote:
> I'm talking about the URL scheme: having a default URL with .../stable/...
> always pointing to the latest stable release would have helped to keep links
> up-to-date. Anyway, the current solution is not the one that you, Marek and
> others were in favor of, so I don't understand the decision.

A default URL with stable would certainly lead to link rot, and links
pointing at pages no longer containing the material you hope to link
to. I would have thought this was obvious.
Various options were discussed, but there was no consensus. I think this
scheme is clear.