-
Notifications
You must be signed in to change notification settings - Fork 394
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
Comments
@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. |
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. |
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. |
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.
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... |
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 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 |
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? |
Fair point, I just researched this a bit more and other Gatsby projects |
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. |
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. |
Yep, using tags + branches (you make a branch from a tag when you need to do some changes) makes total sense to me. |
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. |
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. |
Sounds good. |
Most of mature software have a different version of docs for different stable versions of the software. For example for version
v1
there isdocs/v1/
, for versionv2
there isdocs/v2/
, and so on. For the latest stable version it could be justdocs/
.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 versionv2
(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/
tostatic/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.
The text was updated successfully, but these errors were encountered: