github.com/thanos-io/thanos@v0.32.5/docs/proposals-done/202005-version-documentation.md (about)

     1  ---
     2  type: proposal
     3  title: Building A Versioning Plugin For Thanos
     4  status: complete
     5  owner: thisisobate
     6  menu: proposals-done
     7  Date: May 2020
     8  ---
     9  
    10  ## Problem
    11  
    12  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.
    13  
    14  This proposal aims to solve this by:
    15  
    16  1. building a version picker that serves as a tool which will aid easy access to other versions of the documentation. This picker will include links to change version (the version must be in the URL).
    17  2. providing a documentation structure.
    18  3. designing a workflow for managing docs that integrates with Thanos's Git workflow, i.e. updating corresponding docs on pull requests, cherry-picks, etc.
    19  
    20  ## Motivation
    21  
    22  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.
    23  
    24  ## Requirements
    25  
    26  #### User Story (Latest)
    27  
    28  * As a Thanos developer, I want to be able to just write docs for my current `master` version.
    29  * As a Thanos developer, I want to build the website with versioned docs with a single action.
    30  * As a Thanos developer, I don't want to store duplicated docs in a single repository version.
    31  
    32  #### User Story (Previous release)
    33  
    34  * As a Thanos developer, I want to be able to fix docs for an individual previous release.
    35  * As a Thanos user, I want to be able to read docs for older versions of Thanos.
    36  
    37  #### Use Case
    38  
    39  ##### Users
    40  
    41  Thanos developers, Hugo developers, and general users.
    42  
    43  ##### Precondition
    44  
    45  The user visits the Thanos documentation page.
    46  
    47  ##### Basic Course Of Events
    48  
    49  1. The user indicates that the site is to show a list of docs (both latest and previous releases) by clicking the version picker (dropdown).
    50  2. The site responds by displaying a list of versions allowing the user to make a selection.
    51  3. The user makes a selection and the required docs are rendered on the page/site.
    52  
    53  ##### Postcondition
    54  
    55  The site now has a version picker containing a list of versioned docs consisting of both the latest and older versions.
    56  
    57  ## Proposed Solution
    58  
    59  #### 1. Version Picker
    60  
    61  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`](https://prometheus.io/docs/introduction/overview/), which will enable proper versioning. This user-facing tool will be built using HTML and CSS.
    62  
    63  #### 2. Documentation Structure
    64  
    65  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:
    66  
    67  ```|- website
    68      |- archetypes
    69      |- layout
    70      |- data
    71      |- static
    72      |- resources
    73      |- tmp
    74          |- public
    75          |- docs-pre-processed
    76  ```
    77  
    78  We want to add an additional `versioned` folder within the website's `tmp` directory. For example:
    79  
    80  ```|- website
    81      |- archetypes
    82      |- layout
    83      |- data
    84      |- static
    85      |- resources
    86      |- tmp
    87          |- public
    88          |- docs-pre-processed
    89              |- versioned
    90                  |- master
    91                  |- version 0.13.0
    92                  |- version 0.12.2
    93                  |- other-folder-for-other-releases
    94  ```
    95  
    96  *NOTE: `tmp` directory is not committed, just temporarily built. The current version of docs lives in the `master` folder*
    97  
    98  #### 3. Building a versioning plugin
    99  
   100  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.
   101  
   102  ##### Workflow
   103  
   104  1. The developer makes all the necessary edits in `/docs` on master.
   105  2. The developer proceeds by committing a new release (i.e Release 0.x).
   106  3. CI run some `make web` or `make web-serve` command.
   107  4. Before anything, CI generates the docs and places them in a `versioned` tmp folder.
   108  5. the rest of the web command is executed.
   109  
   110  *NOTE: generated docs are not committed, just temporarily built.*
   111  
   112  ## FAQ
   113  
   114  This section consists of some important questions and answers that are frequently asked by users.
   115  
   116  ##### How do you specify what part of the docs you want to version without cloning every file? docs.yaml
   117  
   118  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:
   119  
   120  ```versioned:
   121     default:
   122     - docs/components/*.md
   123     - docs/storage.md
   124  
   125    overrides:
   126       release-0.12:
   127       - docs/storage2221241.md
   128  ```
   129  
   130  ##### Alternative path
   131  
   132  We could have this file on master, so the current `make web` will
   133  
   134  1. Parse `docs.yaml` from master and use this as a default.
   135  2. Check out each release (e.g. `release-0.10`)
   136  3. Is there docs.yaml?
   137     * Yes - parse the file and use it
   138     * No - use docs.yaml from master
   139  
   140  The design of docs.yaml will look like this:
   141  
   142  ```versioned:
   143     - docs/components/*.md
   144     - docs/storage2221241.md
   145  ```
   146  
   147  ##### What would the plugin look like?
   148  
   149  CLI (`make generate-versioned-docs`)
   150  
   151  ##### What is the plan in terms of plugin placement?
   152  
   153  We hope to start in the Thanos project and then move the project outside to a separate repository.
   154  
   155  ##### How we do fixes to release docs for older release, e.g. v0.12, work?
   156  
   157  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.
   158  
   159  ##### How does the tool discover the releases for fixes?
   160  
   161  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-(.*)`.
   162  
   163  ## Summary
   164  
   165  We understand [Cortex](https://github.com/cortexproject/cortex/pull/2349) is working on this as well so we are learning from their approach and knowledge.
   166  
   167  ## Future Work
   168  
   169  We hope to rewrite the versioning plugin using Golang. We care a lot about code maintainability and because we use Golang as our primary programming language, it will be easier for developers to contribute to this plugin and make it even better.