Daltz333
commented
3 years ago A release process that we (frc-docs) is on a per-year basis. Websites really don't have the concept of rolling-releases like software does, and we don't like following this model.
We have two branches (master/main and stable). During the immediate season (like a sports season), all commits to main update stable. This is disabled during the off-season that way documentation can still progress forward with breaking changes while maintaining stability for the current release (latest vs stable on RTD). At the end of the season, we tag it as the current year (2019, 2020, 2021, etc) for archival purposes. This process works fantastic for us, especially as we have a pretty complex RTD project compared to normal (15-18min build times, 7 translations, and a very large project).
Just wanted to share our setup in-case others wanted a somewhat alternative approach.
It would be good to have a blog post explaining "How to do documentation versioning" and the different approaches that you can do.
There are some articles already,
The problem that I feel with tags as documentation versions is that you are tied or "blocked" there and if you find a simple typo or a code example that doesn't work you can't fix it anymore because the tag is frozen and that doesn't worth a new release of the whole software.
Another example is that you can't change the theme or any Sphinx setting or Read the Docs YAML config option at all.
Mentioning this potential issues in the future could make the user to think twice what approach he/she want to follow when creating RTD versions for the documentation.