Create 2.0.x branch?

[flimzy]

We have a 1.6.x branch for legacy 1.6 documentation, which occasionally gets corrections (at least from me). Now that 2.1.x is nearing release, and 2.0.x is no longer getting new features, we will have a similar situation with the 2.0.x documentation.

My recent PR (#148) appears to touch new features which don't exist in 2.0.x, but it would be nice to update the 2.0.x documentation to reflect the correction made in this PR.

Is creating a 2.0.x documentation branch the best way to do this? And is this a good time to do it?

[wohali]

Hi @flimzy, we can certainly create a 2.0.x branch (immediately from the 2.0.0 label) but it's important to note that https://docs.couchdb.org/en/2.0.0/ will always reflect the content of the 2.0.0 tag, as will the contents of our 2.0.0 release tarball which is frozen at this point.

The branch will only be used if we decide to release a 2.0.1, which seems unlikely at this point.

[flimzy]

Is there any way to update documentation for corrections, after a release is made?

[wohali]

Once we release 2.1 and tag 2.1.0 in the repo, the default https://docs.couchdb.org/ page will redirect to https://docs.couchdb.org/en/2.1.0/. So unless people specifically click on the 2.0.0 link in the documentation footer, they'll always get the updated docs by default. And the 2.0.0 link in the footer will always redirect to the 2.0.0 tag, which we shouldn't (and won't) move. We also can't go back and update the docs we shipped in the 2.0.0 tarball, that asset is frozen.

We could have a 2.0.x link in the website's footer that would follow the 2.0.x branch, but I think that would confuse people. The other thing we could do is release a 2.0.1 with various patches and updated docs, at which point we could tag the docs for 2.0.1 and there'd be a link to that on the website. (That'd require a whole lot of cherry-picking, for what it's worth. 😿 )

@rnewson you were asking about this at one point as well, any opinions?

[flimzy]

That all makes sense. It's a bit unfortunate; I wish it was possible to improve the documentation on the web site, for previous versions. The 1.6 documentation is in a pretty bad state, and while the 2.0 docs are better, there are still a large number of inaccuracies. In both cases, I think the community could greatly benefit from updated, version-specific docs.

[wohali]

I agree. The "right" thing to do is to release a 1.6.2 or 2.0.1 with fixes to the docs.

I'm open to other ideas. For now I'm going to close this ticket.