Show warning header on previous versions of documentation

[simonft]

Description

It might be useful to show a warning at the top of the documentation when viewing versions older than the current release. It's possible to accidentally end up on older versions though searching or old links. It looks like this is a setting in readthedocs already: https://docs.readthedocs.io/en/stable/versions.html#version-warning

User Research Evidence

I somehow ended up on the 1.0.0 documentation, I think either through a link from somewhere else or by my having attempted to visit it directly and my browser auto-completing the url of the documentation from when I was reading it a while ago. I got concerning far into the process before noticing.

[zenmonkeykstop]

It looks like this flag has been set, but the warning isn't showing up. It's possible that it doesn't retroactively apply to older versions unless they're rebuilt - rebuilding 1.0.0 to test.

... and it's still not showing up.

[eloquence]

Thanks again @simonft for the report, another user was just bitten by this issue. Will aim to investigate in the near future.

[emkll]

One way to potentially solve this issue outside of read the docs and reducing the likelihood of serving stale docs would be for stable to always point to the same branch and keep that branch updated: we have a "latest release" branch (for example, master), where we would merge the latest release in that branch on release day. For example, as of yesterday, master would point to the tip of the release/1.2.1 branch

[eloquence]

How does stable currently work? I thought it was meant to always point to the latest release branch, but I'm noticing that it seems to currently still map to 1.2.0 (the 1.2.1 docs are not in there):

https://docs.securedrop.org/en/stable/

[redshiftzero]

stable builds off the latest tag so docs added after the tag is cut are not in the stable build. @emkll has a good idea - we could build a docs branch off master (this would require merging the release branches into master as we used to, HEAD of master would point to the latest release). We then link folks to that branch built off master. This means no broken links and no more linking to individual release-x.y.z branches. We'd just build two branches: master (for users) and latest (for dev purposes built of develop)

[eloquence]

I like that approach, finally a good use for master in this repo! Perhaps we could set up nginx redirects for all the old release-x.x URLs to the master build.

[eloquence]

We should be able to finish this up during the 4/22-5/6 sprint. Thanks again @simonft for the report. As noted in the cross-linked PR above, we now have master pointing to the latest release branch.

Next steps as I understand them:

1. We need to switch stable to build from master instead of the latest release tag.
2. We need to set up redirect patterns in our reverse proxy (assuming RTD's redirect features aren't sufficient) to capture redirects from release-* to stable. The redirects should work on individual docs, not just the base path, so we minimize URL breakage.
3. Once we have deployed and thoroughly tested those, we can remove the release-* branches from the RTD build logic and just keep stable and latest.
4. If there are any implications for the release management process (i.e. updating master after each release), we need to add those to the RM docs.

I'm in favor of keeping the symbolic names stable (master) and latest (develop) so we avoid additional URL changes.

@zenmonkeykstop Does that make sense? If so, could you file a ticket over in infra for the redirect pattern, if that is indeed required?

[redshiftzero]

Recapping this for posterity since we've gone back and forth over the years on the branching strategy for docs builds:

Attempt 1

Two versions of the docs:

• latest -> used to track develop branch. Used for developers.
• “stable” -> built the most recent tag. Used for end users.

Advantages:

• stable pointed clearly to the latest release

Disadvantages:

• docs changes prepared after the latest release meant that they'd not appear in the stable docs without us cutting yet another tag for docs-purposes only

Attempt 2

Many versions of the docs:

• latest -> used to track develop branch. Used for developers.
• release-X where X is a given release -> builds release branches, used for end users.

Advantages:

• No need to cut tags for new docs we want to make available to end users after the tag is cut. We just backport desired docs into the relevant branch.

Disadvantages:

• Users were provided links to release-X which would either break (if we stopped building the docs for that release), or point to out of date information. Led to user confusion as seen in this ticket.

Attempt 3 (what we now do)

Two versions of the docs:

• latest -> used to track develop branch. Used for developers.
• master -> used to build master branch which has release branches merged into it.

Advantages:

• No need to cut tags for new docs we want to make available to end users after the tag is cut. Instead, we just backport those docs into master.
• No user confusion: end users should use the docs built off master. Links don't break.

Disadvantages (just documenting, not saying we should address these yet):

• master branch name can be unclear (used for docs only)
• we need to do the maintenance merges into master branch

[sssoleileraaa]

Attempt 3 (what we now do)

Two versions of the docs:

• latest -> used to track develop branch. Used for developers.
• master -> used to build master branch which has release branches merged into it.

Advantages:

• No need to cut tags for new docs we want to make available to end users after the tag is cut. Instead, we just backport those docs into master.
• No user confusion: end users should use the docs built off master. Links don't break.

Disadvantages (just documenting, not saying we should address these yet):

• master branch name can be unclear (used for docs only)
• we need to do the maintenance merges into master branch

Thanks so much for providing this background on our docs story. What do you think about these steps for improving the current process:

1. when doing the merge from release/<x> into master, squash all commits into a single commit. This is OK since we don’t actually care about the git history on master and it’s used for the purpose of building docs only.
2. make a PR into master

To set us up to continue the discussion on ways to improve how we manage docs, here are the two requirements that I've managed to gather afte picking @redshiftzero's 🧠 (please add more to the discussion if I'm missing anything or doing a terrible horrible no good very bad job of explaining things):

1. have one link that always points to the latest (for developers): https://github.com/freedomofpress/securedrop
2. have one link that always points to the current release after it's been deployed

For req 2 we could use something like: https://github.com/freedomofpress/securedrop/releases/latest but we don't want to show release candidates in the docs as the latest so probably we'd need to use a webhook to come up with a way so that we have a link that always points to the latest that's not an rc - needs investigation... another issue is that we tag before we deploy our packages so we wouldn't want to trigger a new docs build when a new tag is created, instead we'd want to trigger a build after we deploy - probably has to be a manual process?

[sssoleileraaa]

Note about why we never need to point to old releases is that we only support the latest stable version of securedrop and provide upgrade instructions with each release. Also for the workstation there will be more automation to making sure folks are on the latest securedrop.

[redshiftzero]

have one link that always points to the latest (for developers): https://github.com/freedomofpress/securedrop
have one link that always points to the current release after it's been deployed

Yep this is accurate, the third requirement would be to not require us to push a new tag to deploy changes.

cc @zenmonkeykstop - if we want to do something to make it easier to do these maintenance merges like squashing commits into one per release it seems fine to do so (mentioning since this is relevant for the strategy in #5241).