Dvc.org: having docs for different DVC versions

[dashohoxha]

Most of mature software have a different version of docs for different stable versions of the software. For example for version v1 there is docs/v1/, for version v2 there is docs/v2/, and so on. For the latest stable version it could be just docs/.

This makes sense because if people are already using version v1 of the software, and it works well for their needs, they don't have to upgrade to the more advanced version v2 (at least not quickly). However, if they need to consult the docs, they should be able to find the corresponding docs for this version, instead of the docs for the latest version.

It seems that our doc engine should be able to support versioning of the docs easily. For example just copy static/docs/ to static/docs-v1/, make some small configuration somewhere, and done.

I realize that this is not an urgent issue, since DVC itself has not reached a stable release yet ("stable" meaning that the set of features is frozen and is not changed anymore). But still it might be nice to have it ready, especially if it is easy to implement.

[shcheklein]

@dashohoxha good points! I've been thinking about this, and you right that it feels a bit too early for this. I've planned to introduce it when DVC hits 1.0. Thanks for creating a ticket and a very good summary.

[efiop]

Wish we had this feature, the discrepancies we have while getting ready for 1.0 are a real pain :slightly_frowning_face: This would also be very useful during minor releases, as it allows us to have doc pre-releases for dvc pre-releases.

[efiop]

Seems like the docs structure is pretty well-defined by now, so we could probably move them all into a separate git project and just generate different tabs for different tags in it when we deploy the website, so it is not dependant on the changes in our engine. But might be missing something of course.

[jorgeorpinel]

the discrepancies we have while getting ready for 1.0 are a real pain

Unfortunately the Git histories of both repos don't have exact matches, just approximate points at which they sort of matched. BUT these points are unknown — we would need to tag dvc.org when releasing dvc.

we could probably move them all into a separate git project and just generate different tabs for different tags in it when we deploy the website

It's a nice idea 🙂 We have some specific ideas on how to export doc archives for any point in history in #1167, which BTW is kind of a duplicate of this now that I think about it...

[rogermparent]

There's a few ways this could be implemented- well, actually it's a bit of a mix-and-match of solutions to multiple problems.

There's a basic choice on how to actually implement the versioned docs, the two ways we've discussed are storing different versions in the repo directories or accessing different versions from git tags.

I'm heavily for the former, as the latter will force us to make a bunch of big website infrastructural changes (like moving docs content into a separate repo) just to get it to work while the main downside of a file-based solution, extra space used, is mitigated even in a naive copy/paste solution by the fact that our docs are purely text, and as such are negligible in size to copy (for reference, our entire docs content is only 800kb as uncompressed source).

We can also transition into a more advanced file-based implementation down the line in storing descriptions of the differences of the different docs versions to build, which will eliminate the issue of repo bloat as DVC gets more versions.

I know we've been getting away from having the sidebar define docs content, but using a structure similar to the sidebar.json structure to define the different docs versions would be a natural way to make an advanced implementation of a solution to this feature here.

[shcheklein]

@rogermparent

storing different versions in the repo directories

does not feel right to me (that what version control systems for, right?).

On the hand I see that otherwise we'll need to keep updating multiple branches.

So, not sure about this yet.

How do other projects solve this? e.g. Gatsby? any other good examples and mature projects who decided to use Gatsby for docs?

[rogermparent]

Fair point, I just researched this a bit more and other Gatsby projects
This article by Apollo, a well-known big user of Gatsby-based docs, describes their docs theme which use gatsby-source-git to handle versioning, so I'll research that and see how applicable it is to our site.

[rogermparent]

Gatsby's own docs are effectively not versioned, but there's a legacy set of V1 docs on another subdomain at https://v1.gatsbyjs.org/docs/ which leads me to believe Gatsby's using a separate instance entirely for v1 docs.

[rogermparent]

I just checked out Apollo's docs, and while they do use Git they actually use branches instead of tags.

I believe this makes sense, because in a repo the co-locates content and code the code needs to be kept updated even if the content is pinned to an old version. Using branches also opens the possibility of fixing inaccuracies in old versions that possibly have been caught in later ones.

[shcheklein]

Yep, using tags + branches (you make a branch from a tag when you need to do some changes) makes total sense to me.

[jorgeorpinel]

For the record (as mentioned in https://github.com/iterative/dvc.org/issues/1167#issuecomment-624338998) the first 1.0-related PR was #1215 so the last commit in master before that + the 0.94 release updates would make up the last known pre-1.0 docs state. In case we needed to find a good place to branch-off and start trying things.

UPDATE: including #1384 would also be nice.