On Fri, Oct 10, 2025 at 02:47:44PM +0200, Marek Marczykowski-Górecki wrote: > 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.
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. -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion visit https://groups.google.com/d/msgid/qubes-devel/aOozm-swey8H6Bfe%40thirdeyesecurity.org.
