Docs versioning about docs HOT 18 CLOSED

Sorry for my delay, @kuanluo. Your assessment makes sense. I'm good with the drop-down recommendation.

@benesch, what do you think we should have in the drop-down initially? Stable 1.0 and Edge, with the former pointing to https://cockroachlabs.com/docs/stable and the latter pointing to https://cockroachlabs.com/docs/edge?

from docs.

Since I didn't see an existing proposal, I figured I'd submit a strawman RFC for docs versioning here.

• Create a branch for each released major version of CockroachDB: 1.0, 1.1, 1.2, 2.0, etc. For consistency with cockroachdb/cockroach, name these branches release-x.x, as in release-1.0. Right now, we'd only need release-1.0.

• Auto-deploy each release branch to https://cockroachlabs.com/docs/x.x/. 1.0 documentation would live at https://cockroachlabs.com/docs/1.0, for example.

• Auto-deploy the latest-stable documentation to https://cockroachlabs.com/docs/ so that existing URLs continue to work.

• Auto-deploy the tip of gh-pages to https://cockroachlabs.com/docs/edge.

• Don't handle pre-release/unstable versions specially; users on the unstable channel can use the edge docs.

• When deploying, inject <link rel="canonical" href="https://cockroachlabs.com/docs/FOO.html"> into non-default versions of the page with the same filename. So https://cockroachlabs.com/docs/1.0/FOO.html and https://cockroachlabs.com/docs/edge/FOO.html would indicate their canonical URLs as https://cockroachlabs.com/docs/FOO.html. This should prevent Google from linking to non-default of pages, unless those old versions are legitimately far more relevant to the search query. (Old versions of PostgreSQL documentation, for example, frequently appear in Google results.) Pages that do not yet exist in the default version (e.g. https://cockroachlabs.com/docs/edge/NEW-FEATURE.html) would not list a canonical URL.

• Backport commits on gh-pages to release branches as necessary.

• Consult with design to build a version switcher.

The downside of this approach is that nearly every commit on gh-pages in the next few weeks will need to be backported to release-1.0. I don't see a great way around that, considering we've already started landing 1.1 features to master that will need documentation but won't make it into the 1.0.x series.

/cc @bdarnell @sploiselle

from docs.

Your proposal looks very good to me, @benesch! Thanks for writing it up. Adding @mjibson since I've discussed basic approaches with him, too.

In terms of "backporting commits" from gh-pages to a release branch, that's what we would do for any patch releases that need to be reflected in that version's docs as well as for any doc bugs we decided need to be fixed, is that right? And how would it work exactly? It's something I haven't yet done in git.

from docs.

Also, just to make sure we're on the same page, my feeling is that docs versioning doesn't need to be in place for the 1.0 release date. Instead, it needs to be in place for 1.1, at the latest. @benesch, do you agree?

from docs.

Overall that proposal looks good. One change I'd make regarding the canonical links is to instead make the non-canonical versions include a noindex meta tag, which will prevent google from indexing them, but also continue to work if we delete, create, or rename pages, which would break the canonical links. Although maybe it's ok if the canonical links are broken? I'm not sure how google handles that.

from docs.

Really thoughtful and considerate sketch here. A few more considerations (questions, not answers):

• Can we easily control backporting/moving content forward with some kind of front-matter tagging? i.e. something like "Version Support: 1.0+" or "1.0, 1.2".
• Do we want to attempt smart redirections when visitors try to load pages that exist in other versions, but not in this one? e.g. if /docs/deprecated.html got killed in the 1.2 release, do we want to try and serve them the content we know they're looking for? Alternatively, we can keep every page that ever existed in the current repo with a link to the last version it lived in, but that feels tedious.
• Kind of the converse of the prior point, what if you try to go to 1.0/newfeature.html, which exists only in the 1.1 and forward repos?

from docs.

@mjibson, my concern with marking old versions as noindex is that sometimes you might actually want that old version. Perhaps the old version includes a note like "you'll see error foobazle if you try to frobulate the bargoon" and you're searching for "foobazle when frobulating bargoon in cockroachdb". If those old versions aren't indexed, you're out of luck.

Re deletions/renames: I figured we could write a quick script to insert <link rel="canonical" ...> into the generated files iff a file with the same name exists in the current stable version.

@jseldess, yup! We need to have this set up when you want to publish documentation that only applies to the latest unstable version. That'll be sooner than 1.1, I think, but definitely after 1.0.

from docs.

Ok. Having a thing that can make sure the canonical links work seems fine to me.

from docs.

@sploiselle, answers inline:

• Can we easily control backporting/moving content forward with some kind of front-matter tagging? i.e. something like "Version Support: 1.0+" or "1.0, 1.2".

Not easily, I don't think. (Perhaps someone else has a solution?) The trouble stems from small changes to existing features: e.g., when we add/remove a flag to cockroach start, there's a small section of the "Start a Node" documentation that needs to change from version to version.

• Do we want to attempt smart redirections when visitors try to load pages that exist in other versions, but not in this one? e.g. if /docs/deprecated.html got killed in the 1.2 release, do we want to try and serve them the content we know they're looking for? Alternatively, we can keep every page that ever existed in the current repo with a link to the last version it lived in, but that feels tedious.

That's a good point! We'll be breaking bookmarks when we publish docs for a new version if we've removed/renamed pages. Should be possible to auto-generate these "feature deprecated" pages using whatever pipeline we set up for automatically generating canonical links.

• Kind of the converse of the prior point, what if you try to go to 1.0/newfeature.html, which exists only in the 1.1 and forward repos?

I'm less worried about this case, because you'll have to manually hack the URL to end up there. We should definitely make sure the version switcher excludes pages that don't exist in that version, though.

@jseldess, to answer your question about backporting, in the easy case, it's quite simple. You essentially open the PR twice: once against the gh-pages branch and once against the release-x.x branch. Here's an example of Marc backporting a fix from master onto release-1.0.

Where it gets tricky is when you've completely rewritten a doc for the new version. Say, hypothetically, we completely rewrite the install instructions page for version 1.1. If we later decide we want to document that both 1.0 and 1.1 require macOS 10.9 and newer, you'd likely have to make the change separately on the 1.0 and 1.1 branches. When the versions have diverged significantly, Git won't be able to automatically determine where to apply the change.

from docs.

Thanks again for thinking this through, @benesch. I'll set up a meeting early next week for us to nail down the approach. I'll make it @sploiselle, @benesch, @mjibson, and me.

@bdarnell, @mberhault, @petermattis, let me know if you'd like to be there as well.

from docs.

@jseldess, @benesch, @mjibson, @sploiselle
Attached is the favored design for versioning:

When you click on the button, the dropdown opens like the rest of the nav:

from docs.

Thanks, @kuanluo! Looks great. I'm wondering if we're overloading the drop-down feature, though. Would you be willing to mock a hover feature as well, similar to what Django does, but in the same spot on the left?

from docs.

Most recent versioning thoughts are in Docs Versioning.

@benesch, any updates on the plan to try out the single branch with multiple subdirectories approach we discussed a few weeks ago?

@sploiselle, you mentioned being willing to map out all the edge scenarios between versions and how the site should behave. Do you want a separate issue to track that work?

from docs.

Created #1474

from docs.

@jseldess I'm not sure if Django's versioning is better for us. My thinking stemmed mostly from these two reasons:

• Consistency: Dropdown is a known interaction on docs, and if possible, I'd like to minimize the different interactions we have, especially when we don't quite know how people will interact with this feature yet.
• Ability to go back to much older versions of docs past 2.4. Django only allows one to go back so far. And dropdown seems to be a common behavior for versioning.

What do you think? Thanks!

from docs.

@benesch, the only work remaining now is #1546 (moving the sql generator to the cockroach repo), is that right? If so, I'll close this issue and focus on that other one.

from docs.

From the eng end, yep! I know @kuanluo wanted Division Of to tweak the mobile styles, though.

from docs.

Nice. I know DO is already working on the mobile styles.

from docs.