- Author: Jay Batra
- Date: March 2020
- Status: proposal
In Cortex, currently, we are missing versioning of documentation. The idea is to have version documentation just like Prometheus.
Prometheus. Documentation is the main source of information for current contributors and first-timers. A properly versioned documentation will help everyone to have a proper place to look for answers before flagging it in the community.
In this proposal, we want to solve this. In particular, we want to:
- Version specific pages of the documentation
- Include links to change version (the version must be in the URL)
- Include the master version and last 3 minor releases. Documentation defaults to the last minor release.
Currently, the documentation is residing under the docs/ folder of cortexproject/cortex. It is built by Hugo using the theme
docsy. It will have a proper
drop-down menu which will enable proper versioning. It has a section
params.version in config.toml which will allow us to map URLs with proper versions. We will have to change all the occurrences of older doc links with new links. We will keep
master version with 3 latest
release versions. Each release is a minor version expressed as
1.x. The document would default to latest minor version.
From the current doc, the following paths (and all their subpages) should be versioned for now:
- https://cortexmetrics.io/docs/configuration/ (moving v1.x Guarantees outside of the tree, because these shouldn’t be versioned)
The above should be versioned under a single URL path (
/docs/running-cortex/ in the following example, but final prefix is still to be decided).
master version we would be able to use the above links via the following path
And for a minor version like
we’ll have versioned documentation only under the /docs/running-cortex/ prefix and, as a starting point, all versioned pages should go there.