Release-specific documentation

[andrewdavidwong]

Update

This effort has been subsumed by the migration to Read the Docs:

https://groups.google.com/g/qubes-devel/c/ASj7tehn1G0/m/fA33ylhHAgAJ

It is likely that much of the content below is out-of-date. Interested parties are encouraged to read the thread just linked above instead.

Overview

• We will maintain a separate set of documentation for each major and minor Qubes OS release (e.g., R1, R1.1, R2, R3, R3.2).
• We will not maintain separate sets of documentation for patch releases (e.g., R1.0.1, R1.0.2, R1.0.3).
• Each release-specific set of documentation will be managed in its own Git branch.
• Each page will be reviewed and have a status message indicating whether its contents have been approved for that release (examples below).
• The release of a given documentation page will be visible in two ways: the URL (e.g., https://www.qubes-os.org/doc/r4/installation-guide/) and in the review status message on the page itself.

Review Status Examples

Procedures

In order to maintain multiple releases correctly:

• Do not specify a permalink: in the YAML header of any release-specific documentation page. Instead, allow the permalink to be generated by the contents of _config.yml.
• When reviewing pages for a new release, add approved_release: RX (where X is the release number) on its own line in the YAML header. Without this line, there will be a warning that the page has not yet been approved for release X. With this line, there will be a notification that the page has been approved for release X.

For each new major Qubes OS release:

1. Create a new qubes-doc Git branch for that release.
2. Update the release number in the following files:

   _config.yml
   _includes/doc-heading.html
   _includes/doc-rX-approved.html
   _includes/doc-rX-unapproved.html
   

3. Connect the new branch as a separate module in the main repo.
4. Update URL redirects so that unreleaseed URLs point to the new release.
   (TODO: Write a script for this.)

Related Issues

#3495

[andrewdavidwong]

@marmarek, I think we're going to need this again for 4.1. However, I don't want to step on the toes of the localization push. Do you think it's better to wait?

[marmarek]

Yes, it will conflict, so better wait...

[andrewdavidwong]

I think we're going to need this again for 4.1.

On second thought, this shouldn't be required for 4.1 if the documentation is to be specific to each major release. In that case, we shouldn't really need this until release 5.0.

[andrewdavidwong]

In a separate discussion, it was determined that we will try to implement release-specific docs while preserving permalinks. So far, my approach has been to specify the release number in the permalink, e.g., /doc/4.0/foo/. This is fairly easy to handle with a simple bulk sed command.

However, how should we handle redirects? Many of these pages have historical lists of redirects. Should these lists be preserved only on the latest stable release's version of that page? That seems more difficult to handle without some fancier scripting.

Moreover, what about other links around the website that point to release-specific doc pages? For example, there are a lot of links in the footer of each page ("architecture" links). Many of these will have to be made release-specific, but it's unclear how to handle that, given that only a subset of the documentation is to be made release-specific, not the entire website.

@marmarek, do you have any thoughts about this?

[tokideveloper]

@andrewdavidwong
In order to answer your questions, I propose the following:

Assuming the file user/how-to-guides/how-to-enter-fullscreen-mode.md is to be made release-specific:

---
lang: en
layout: doc
permalink: /doc/how-to-enter-fullscreen-mode/
redirect_from:
- /doc/full-screen-mode/
- /en/doc/full-screen-mode/
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
ref: 205
title: How to enter fullscreen mode
---

What is fullscreen mode?
-------------------------

Normally, the Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, […]

We could make it release-specific by moving its content to a file like user/how-to-guides/how-to-enter-fullscreen-mode-4.0.md like this:

---
lang: en
layout: doc
permalink: /doc/4.0/how-to-enter-fullscreen-mode/
title: How to enter fullscreen mode (R4.0)
---

What is fullscreen mode?
-------------------------

Normally, the Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, […]

Note the additional "(R4.0)" in the title and the new permalink. Also note that a new "ref" number will be drawn.

The original file user/how-to-guides/how-to-enter-fullscreen-mode.md, however, becomes a "router" to the release-specific versions of that topic:

---
lang: en
layout: doc
permalink: /doc/how-to-enter-fullscreen-mode/
redirect_from:
- /doc/full-screen-mode/
- /en/doc/full-screen-mode/
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
ref: 205
title: How to enter fullscreen mode
---

This topic is release-specific.
Please, choose your Qubes OS version:

- [R4.0](/doc/4.0/how-to-enter-fullscreen-mode/)
- [R4.1](/doc/4.1/how-to-enter-fullscreen-mode/)

Note that the whole YAML front matter is preserved. This way, we won't get any broken links, redirects or "architecture". However, the user has to choose the Qubes OS version instead of being redirected to the most recent one but that's fine I think (if I were the user).

Note that the content of the "router" file can also be created dynamically. So, the file could look like this (no content there, just an additional "releases" key):

---
lang: en
layout: doc
permalink: /doc/how-to-enter-fullscreen-mode/
redirect_from:
- /doc/full-screen-mode/
- /en/doc/full-screen-mode/
- /doc/FullScreenMode/
- /wiki/FullScreenMode/
ref: 205
title: How to enter fullscreen mode
releases:
- 4.0
- 4.1
---

What do you think about this?

[andrewdavidwong]

We could make it release-specific by moving its content to a file like user/how-to-guides/how-to-enter-fullscreen-mode-4.0.md like this: [...]

I don't think it's necessary to put the release number in the filename. Directory is enough (see https://github.com/QubesOS/qubes-doc/tree/release-specific-docs).

Note the additional "(R4.0)" in the title and the new permalink.

I think just the permalink is enough, as the release number will also be in the large heading at the top of the page and in the alert stating whether it has passed review for that release.

Also note that a new "ref" number will be drawn.

Yes.

The original file user/how-to-guides/how-to-enter-fullscreen-mode.md, however, becomes a "router" to the release-specific versions of that topic: [...] Note that the whole YAML front matter is preserved. This way, we won't get any broken links, redirects or "architecture". However, the user has to choose the Qubes OS version instead of being redirected to the most recent one but that's fine I think (if I were the user). Note that the content of the "router" file can also be created dynamically. So, the file could look like this (no content there, just an additional "releases" key): [...]

This is an interesting idea. In general, I like it, but I'm still not sure if it's a good idea to have so many permanent architecture links pointing directly to such "disambiguation" pages rather than directly to useful content. Ideally, they would all point to the latest stable release versions, but I can't think of any way to automate that or easily script it while retaining permalinks. This may be the best we can do.

[Edit: On second thought, maybe it wouldn't be so bad just to do a find-and-replace on architecture.yml each time there's a new stable release.]

Another thing is that it might get confusing to have a different version of this file for every release and a non-release-specific version of the same file that just serves as a "router." Someone who searches for key words in the filename will find at least three identical-sounding files (plus one more for each subsequent release beyond 4.1). But at least it should be clear that the "router" is not a content file after looking at the file contents and/or the parent directory path.

[tokideveloper]

We could make it release-specific by moving its content to a file like user/how-to-guides/how-to-enter-fullscreen-mode-4.0.md like this: [...]

I don't think it's necessary to put the release number in the filename. Directory is enough (see https://github.com/QubesOS/qubes-doc/tree/release-specific-docs).

Ah, okay, seems enough.

Note the additional "(R4.0)" in the title and the new permalink.

I think just the permalink is enough, as the release number will also be in the large heading at the top of the page and in the alert stating whether it has passed review for that release.

In my view, different contents should have different titles. But it's just my taste.

The original file user/how-to-guides/how-to-enter-fullscreen-mode.md, however, becomes a "router" to the release-specific versions of that topic: [...] Note that the whole YAML front matter is preserved. This way, we won't get any broken links, redirects or "architecture". However, the user has to choose the Qubes OS version instead of being redirected to the most recent one but that's fine I think (if I were the user). Note that the content of the "router" file can also be created dynamically. So, the file could look like this (no content there, just an additional "releases" key): [...]

This is an interesting idea. In general, I like it, but I'm still not sure if it's a good idea to have so many permanent architecture links pointing directly to such "disambiguation" pages rather than directly to useful content. Ideally, they would all point to the latest stable release versions, but I can't think of any way to automate that or easily script it while retaining permalinks. This may be the best we can do.

Since there exist different versions of Qubes OS, I would expect "disambiguation" pages or something like that.

[Edit: On second thought, maybe it wouldn't be so bad just to do a find-and-replace on architecture.yml each time there's a new stable release.]

That's a good idea!

We could also add a link back to the "disambiguation" page on every disambiguated page using Liquid. So, if a user lands on a R4.1 page, they could go back to the "disambiguation" page and choose the R4.0 page for example.

Another thing is that it might get confusing to have a different version of this file for every release and a non-release-specific version of the same file that just serves as a "router." Someone who searches for key words in the filename will find at least three identical-sounding files (plus one more for each subsequent release beyond 4.1). But at least it should be clear that the "router" is not a content file after looking at the file contents and/or the parent directory path.

I think the user already knows the context (via the working directory) when searching or the search result will reveal the path (4.1/, 4.0/ etc.). We cannot avoid identical-sounding files (unless we name them like *-4.1.md, *-4.0.md, *-disambiguation.md) since their topics are equal.

[andrewdavidwong]

In my view, different contents should have different titles. But it's just my taste.

In principle, I'm not opposed, but I can't think of any easy way to automate or script it right now.

[unman]

On Sat, Sep 25, 2021 at 09:02:04PM -0700, Andrew David Wong wrote: > In my view, different contents should have different titles. But it's just my taste. In principle, I'm not opposed, but I can't think of any easy way to automate or script it right now.

I could script this in awk, to insert in the Title from the permalink, if its wanted?

[andrewdavidwong]

I could script this in awk, to insert in the Title from the permalink,
if its wanted?

No, we decided a while back that there are too many cases in which generating the title from the permalink would be problematic. Thank you, though.

[tokideveloper]

I could script this in awk, to insert in the Title from the permalink,
if its wanted?

No, we decided a while back that there are too many cases in which generating the title from the permalink would be problematic. Thank you, though.

I think @unman thought of extracting just the release version number from the permalink and appending it to the title. Not the whole permalink, just the release version number.

For example, given a file with

permalink: /doc/4.0/how-to-enter-fullscreen-mode/
title: How to enter fullscreen mode

the result of the awk script would be the equal file but with

title: How to enter fullscreen mode (R4.0)

in the YAML front matter. Is that right?

(By the way, the script should work idempotently.)

[unman]

On Mon, Sep 27, 2021 at 07:17:30AM -0700, Tobias Killer wrote: > > I could script this in awk, to insert in the Title from the permalink, > > if its wanted? > > No, we decided a while back that there are too many cases in which generating the title from the permalink would be problematic. Thank you, though. I think @unman thought of extracting just the release version number from the permalink and appending it to the title. Not the whole permalink, just the release version number. For example, given a file with ``` permalink: /doc/4.0/how-to-enter-fullscreen-mode/ title: How to enter fullscreen mode ``` the result of the awk script would be the equal file but with ``` title: How to enter fullscreen mode (R4.0) ``` in the YAML front matter. Is that right? (By the way, the script should work idempotently.)

Yes, to both points.

[andrewdavidwong]

Thank you. That could be useful if we proceed with this (as would similar scripts). However, we are currently evaluating whether to migrate to another documentation platform (see the recent thread in qubes-devel), which might supersede this.

[andrewdavidwong]

This effort has since been completely taken over by the migration to Read the Docs:

https://groups.google.com/g/qubes-devel/c/ASj7tehn1G0/m/fA33ylhHAgAJ

[andrewdavidwong]

This effort has since been completely taken over by the migration to Read the Docs:

https://groups.google.com/g/qubes-devel/c/ASj7tehn1G0/m/fA33ylhHAgAJ

Also see:

• Transition the Qubes documentation to the Read the Docs (RTD) platform #8180