Some tutorials link to files in the master branch instead of their version branch

[creachadair]

A follow-up to #7674.

A number of Markdown files in the docs directory, notably the tutorials, link to versions of files at the tip of the master branch instead of the version for which the tutorial is generated. This gives confusing results on the doc site, where the actual contents (and sometimes locations) of files may have diverged on the development head.

It would be nice to automate branching this in some way, since the values may change between versions even within a release branch.

Work Items

• 🆗 Fix up absolute links that point to docs.tendermint.com/master/spec. (we wound up backing out the removal of docs from master, so this is now moot)
• Fix up links imported from the spec repo to point to tendermint/tendermint (docs: Update spec links to point to tendermint/tendermint #7851).
• Rewrite the branch-based links on v0.33.x (Update absolute links in v0.33.x to reference that branch. #7887), v0.34.x (Update absolute links in v0.34.x to reference that branch. #7871), and v0.35.x (Update absolute links in v0.35.x to reference that branch. #7870) to target their branch.
• Drop master from the generated docs site entirely (Remove master from the docs site version config. #7874).
• Remove RFC and ADR documents from v0.33.x (Remove ADR docs from the v0.33.x backport branch. #7879), v0.34.x (Remove ADR and RFC docs from the v0.34.x backport branch. #7867), and v0.35.x (Remove ADR and RFC docs from the v0.35.x backport branch. #7866).
• Add to the release docs a step: When cutting a new backport branch, do the same path rewriting for that backport branch (Update release instructions for documentation. #7846).

[creachadair]

Fixing this turns out to be a little more complicated than it appears.

The advice from DOCS_README.md is that "Relative links should be used nearly everywhere", because it "works both on GitHub and for the VuePress build". The latter is true, but unfortunately insufficient.

The specific problem is that the docs site is rooted at the docs directory, not the root of the repo. So links to other documentation pages need to be relative to that. However, because of the different rooting, links to other repository files cannot be made relative, because they traverse past the root of the URL.

So we can fix the targeting of links within the doc site, but not outside it.

We might be able to fix this for the docs site build by tweaking the VuePress config (e.g., inserting placeholders and substituting them for the target branch during the build). If we do that, however, then the links within the repository will no longer work, which will break markdown link checking and various other automation (along with readers' ability to move around when navgiating the repo on GitHub).

[cmwaters]

Why is it not possible to use absolute URL's for links outside the docs directory?

Is this just a problem because we copy the entire spec across?

[creachadair]

Why is it not possible to use absolute URL's for links outside the docs directory?

Is this just a problem because we copy the entire spec across?

That is what we do now. The problem with absolute links is that they require embedding the branch name to form the URL. Presently, we do that using master, which means the docs site points to the master copy regardless of which version is selected, and master diverges from what is in the docs for previous versions.

If we stub in a placeholder for vuepress to rewrite, then those links will appear as broken when viewed from GitHub directly, which means they'll fail in the link checker.

[cmwaters]

So one option could be that whenever we create a backport branch we also update the docs to shift away from master and now to the backport branch? I'm not even convinced we should have documentation for master anyway since everything's in flux and we recommend people to use versions

[creachadair]

So one option could be that whenever we create a backport branch we also update the docs to shift away from master and now to the backport branch?

Yes. That's what I'm leaning toward. It wouldn't be hard to script rewriting URLs that point to the master branch of some file to target the backport branch instead. It would need to be done after creating the branch (of course) and committed against it before cutting a release.

I'm not even convinced we should have documentation for master anyway since everything's in flux and we recommend people to use versions

That's a reasonable take. I don't have a strong feeling about keeping master on the doc site, but I would prefer that links viewed on GitHub continue to work when viewing the master branch.

[creachadair]

Summarizing the discussion about this issue during the dev call, we generally agreed the simplest solution is to continue using absolute URLs, so that links will work both in GitHub and in the generated docs site.

Roughly, the plan is:

• Rewrite the branch-based links on v0.34.x and v0.35.x to target their branch.
• Clean up any path disjunction between those branches and master.
• Drop master from the generated docs site entirely.
• Add to the release docs a step: When cutting a new backport branch, do the same path rewriting for that backport branch (once).

[creachadair]

I believe this is now done.