The Thanos website contains the docs area which is built by rendering the markdown files from the tip of master of the Thanos repository. This frequently causes confusion for users, as different Thanos versions have different features.
This proposal aims to solve this by:
Many users (mostly developers) often want to look through the docs of previous releases, but searching for them manually by looking through the entire GitHub repository is time-consuming and ineffective. The site is built by rendering the markdown files from the tip of master of the Thanos repository, which causes confusion for users, as breaking changes are often merged into master. The versioning plugin allows the user to access the docs of both latest and previous releases on the Thanos documentation page, and it also allows the developer to fetch, write, and fix the docs of both latest and previous releases.
master
version.Thanos developers, Hugo developers, and general users.
The user visits the Thanos documentation page.
The site now has a version picker containing a list of versioned docs consisting of both the latest and older versions.
Currently, the documentation resides under the docs/ folder of the Thanos repository. It is built by Hugo. It will have a proper drop-down menu just like the Prometheus website’s drop-down menu
, which will enable proper versioning. This user-facing tool will be built using HTML and CSS.
We want to propose a method called “Directory Sub Branching”. Directory Sub branching means creating different sub branches in the versioned
folder of the Thanos repository. Since the current architecture of the Thanos website is this:
|- archetypes
|- layout
|- data
|- static
|- resources
|- tmp
|- public
|- docs-pre-processed
We want to add an additional versioned
folder within the website’s tmp
directory. For example:
|- archetypes
|- layout
|- data
|- static
|- resources
|- tmp
|- public
|- docs-pre-processed
|- versioned
|- master
|- version 0.13.0
|- version 0.12.2
|- other-folder-for-other-releases
NOTE: tmp
directory is not committed, just temporarily built. The current version of docs lives in the master
folder
Creating a plugin that can automate these processes would save us a lot of development time and stress. This approach promises to be useful when it comes to versioning different release in the Thanos website.
/docs
on master.make web
or make web-serve
command.versioned
tmp folder.NOTE: generated docs are not committed, just temporarily built.
This section consists of some important questions and answers that are frequently asked by users.
We hope to have a single, flexible configuration file (docs.yaml
) that will help the developer in specifying what part of the docs they need without cloning all the docs. We could have this as a single file on master. The config file will look like this:
default:
- docs/components/*.md
- docs/storage.md
overrides:
release-0.12:
- docs/storage2221241.md
We could have this file on master, so the current make web
will
docs.yaml
from master and use this as a default.release-0.10
)The design of docs.yaml will look like this:
- docs/components/*.md
- docs/storage2221241.md
CLI (make generate-versioned-docs
)
We hope to start in the Thanos project and then move the project outside to a separate repository.
We will edit the particular release (release-0.12) branch and add a commit. The then tool fetches the latest commit on this branch and uses it to generate the docs. We expect to fetch docs for minor releases without breaking them with patches. We encourage immutability across all our release tags in Thanos.
With a regular expression. Instead of the developer manually checking out the individual release branches, the tool handles it for them by using a regex to select and clone valid release branches. The config file for the tool will have a release-branch-regex
field. For Thanos, the regular expression would be something like release-(.*)
.
We understand Cortex is working on this as well so we are learning from their approach and knowledge.