Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

having docs for different DVC versions #593

Closed
dashohoxha opened this issue Aug 27, 2019 · 13 comments
Closed

having docs for different DVC versions #593

dashohoxha opened this issue Aug 27, 2019 · 13 comments
Labels
A: website Area: website status: research Writing concrete steps for the issue type: enhancement Something is not clear, small updates, improvement suggestions website: eng-doc DEPRECATED JS engine for /doc

Comments

@dashohoxha
Copy link
Contributor

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
Copy link
Member

@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.

@shcheklein shcheklein changed the title Having docs for different DVC versions having docs for different DVC versions Aug 28, 2019
@shcheklein shcheklein added A: docs Area: user documentation (gatsby-theme-iterative) website: eng-doc DEPRECATED JS engine for /doc type: enhancement Something is not clear, small updates, improvement suggestions labels Aug 28, 2019
@shcheklein shcheklein added A: website Area: website and removed A: docs Area: user documentation (gatsby-theme-iterative) labels Apr 9, 2020
@efiop
Copy link
Contributor

efiop commented Jun 2, 2020

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

@efiop
Copy link
Contributor

efiop commented Jun 2, 2020

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
Copy link
Contributor

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 iterative/gatsby-theme-iterative#35, which BTW is kind of a duplicate of this now that I think about it...

@rogermparent
Copy link
Contributor

rogermparent commented Jun 3, 2020

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
Copy link
Member

@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
Copy link
Contributor

rogermparent commented Jun 4, 2020

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
Copy link
Contributor

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
Copy link
Contributor

rogermparent commented Jun 4, 2020

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
Copy link
Member

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

@jorgeorpinel jorgeorpinel added the status: research Writing concrete steps for the issue label Jun 5, 2020
@jorgeorpinel
Copy link
Contributor

jorgeorpinel commented Jun 5, 2020

For the record (as mentioned in iterative/gatsby-theme-iterative#35) 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.

@shcheklein
Copy link
Member

Let's close this. Let's try to keep notes (feature flags) for now. Too painful to support too many versions. We can revisit it later.

@jorgeorpinel
Copy link
Contributor

Sounds good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A: website Area: website status: research Writing concrete steps for the issue type: enhancement Something is not clear, small updates, improvement suggestions website: eng-doc DEPRECATED JS engine for /doc
Projects
None yet
Development

No branches or pull requests

5 participants