New blog post: Documentation Versioning #74
Conversation
There was a problem hiding this comment.
Good post -- we should also update our docs with this content. I think it needs a bit more of a workflow defined. I think GitHub Flow is perhaps a good model to follow here.
We should also define the tense we're writing in. We switch from you to our, and we should keep it in one style. Are we talking about ourselves, or about the user?
| * ``1.0.x`` is a release branch for the ``1.0`` version | ||
| * ``1.0.3`` is a similar tag for your ``1.0.x`` branch, with the latest release | ||
| * ``1.0.0`` is the first tag for your ``1.0.x`` branch. | ||
|
|
There was a problem hiding this comment.
I feel like we need to expand more on this. This mostly matches what I had here: https://www.ericholscher.com/blog/2016/jul/1/sphinx-and-rtd-for-writers/#recommended-versioning-system -- but what do we do with the tags and old links to 1.0.3 when 1.0.4 is released? I think we need a bit more guidance there.
There was a problem hiding this comment.
Yes. I took the inspiration from there and my goal was to expand it and make it better. I failed 🙂
There was a problem hiding this comment.
I think the key is that if there will be more 1.0.x releases, there should be a release branch and documentation builds off that branch. If you have a typo in the docs or an example in the docs that doesn't work, you just make a new version and the 1.0.x docs get updated.
It also depends on whether there will be multiple concurrent versions. For example, Django is currently supporting 1.11.x, 2.1.x and 2.2.x and there are large differences between these. Users definitely should be looking at the right docs for their version.
If instead, you just want to have a few old versions of the docs around for users using the old stuff then I think tags are mostly fine. However, again if you're following semver you probably don't need docs for 1.0.3 and 1.0.4. I think that's worth mentioning in this post!
There was a problem hiding this comment.
if you're following semver you probably don't need docs for 1.0.3 and 1.0.4
I mean you have the docs in VCS but you don't need published docs for both when they're basically exactly the same.
I agree. I'm working on trying to make it better.
I think that explaining this flow is out of the scope of this blog post. Although, I think it would be good to link this page, which is really nice: https://guides.github.com/introduction/flow/. It doesn't talk about "release branches", though. |
|
You may probably refers to |
There was a problem hiding this comment.
I think rather than saying there's one way to version documentation, we should highlight a few alternatives, discuss their trade-offs, and give example projects using that strategy:
- The latest/stable + tags strategy - This is appropriate for smaller projects especially when they aren't supporting multiple concurrent releases and they are mostly compatible between versions. This can be combined with having a few documentation versions from tags (you don't need all of them if
1.0.3and1.0.4follow semver for example, but1.0.0and1.1.0seem good to have). This is probably appropriate if all your releases are tags from themasterbranch as opposed to the release coming off of another branch. It's a drawback of this strategy that changing documentation after the fact is challenging/impossible/hacky because it would involve rewriting tags. - Release branch strategy - This is appropriate for larger projects and definitely where multiple concurrent versions are supported. For example, the Django 1.11.x docs and the 2.2.x docs are very different but both minor versions are actively being supported and there are bugfix releases on them. They call the branches
stable/1.11.xandstable/2.2.xrespectively. For example, release2.2.0,2.2.1, and2.2.2all were branched off ofstable/2.2.xrather thanmaster. In fact,1.11.22was released at the same time as2.2.3and contains the same bugfixes. - Other strategies? - I'd look at our top 20-30 projects and see what they do. Do they all fit these two strategies? I bet there is a little bit of variation and that could make for something interesting!
| ======================================== | ||
|
|
||
| Project releases and documentation versions are strongly related each other. | ||
| You usually want to have a release ``1.0.3`` with it's own documentation version ``1.0.3`` for that specific release. |
There was a problem hiding this comment.
Django and Flask don't do this. I'd actually say if you're following semver you probably don't need to document below the minor version level (eg. 1.0.x).
| * ``1.0.x`` is a release branch for the ``1.0`` version | ||
| * ``1.0.3`` is a similar tag for your ``1.0.x`` branch, with the latest release | ||
| * ``1.0.0`` is the first tag for your ``1.0.x`` branch. | ||
|
|
There was a problem hiding this comment.
I think the key is that if there will be more 1.0.x releases, there should be a release branch and documentation builds off that branch. If you have a typo in the docs or an example in the docs that doesn't work, you just make a new version and the 1.0.x docs get updated.
It also depends on whether there will be multiple concurrent versions. For example, Django is currently supporting 1.11.x, 2.1.x and 2.2.x and there are large differences between these. Users definitely should be looking at the right docs for their version.
If instead, you just want to have a few old versions of the docs around for users using the old stuff then I think tags are mostly fine. However, again if you're following semver you probably don't need docs for 1.0.3 and 1.0.4. I think that's worth mentioning in this post!
Co-Authored-By: David Fischer <[email protected]>
|
Marking this as WIP because I want to revisit and re-write some sections after the feedback that I received and the discussion we have. |
|
I revisited this PR twice this month and I'm still stuck thinking what's the recommendation I feel comfortable communicating to the audience. In the end, I found myself wanting version aliases combined with automation rules:
That will give me these type of versions, for example:
(all the versions that are not alias are Instead of putting the effort on the release process, we build a feature around it that makes it automatically for the users. I really like what @davidfischer said in the last comment. However, I think the size of the project shouldn't be the main difference. I think that even if we are not maintaining
Summarizing, I'd like to promote two options whenever that would be possible:
The others are too complicated in my opinion, require a specific branch naming in your VCS, point users to old documentation (fixed patch version tag), etc. |
| Recommended versioning strategy | ||
| ------------------------------- | ||
|
|
||
| **The workflow we recommend for versioning your documentation is having release branches.** |
There was a problem hiding this comment.
I get that this idea effectively encourages projects to follow Trunk Based Development https://trunkbaseddevelopment.com/ but there are other schemes https://www.toptal.com/software/trunk-based-development-git-flow
I wonder how applicable this is for projects not following Trunk Based Development
|
I'm going to distill some of these ideas in the tutorial readthedocs/readthedocs.org#8473 |
|
(Edit, wrong link) |
This is my first post on Read the Docs' blog.
I tried to achieve what we have talked about Documentation Versioning mentioning what are the most common problems and what's the solution that we are proposing.
Overall, I like the post, but I feel that the solution proposed needs more strength to catch people's attention.
I'm open to suggestion on every single word --or even, rewriting it completely ;)
Rendered version: https://readthedocs-blog--74.org.readthedocs.build/documentation-versioning/
Closes #53