How do we switch between versions?

[alexander-yevsyukov]

Gradle and K9s do this via drop down menu in the site header?

Gradle uses a separate site for documentation, having each version in a sub-directory under the site.

K9s switches the whole site, having previous versions under a separate domain name.

[alexander-yevsyukov]

@meizabel, we need to decide on this before v1.0 release. We do not want to be blocked by this issue when we want to release v1.1, or even v1.0.1.

[alexander-yevsyukov]

@JuliaEvseeva, @andreySadomovskiy, what's your take on this issue?

[meizabel]

I would stick to the following pattern for each major release:

1. Have a new version of documentation.
2. Create and publish Release Notes. Usually accessible in Documentation section on site/wiki or similar.
3. Create a blog post and publish an announcement on the new version enhancements/bug fixes and provide a link to Release Notes.

An idea to have a separate site for documentation with each version as a sub-directory is rather common. We can refer to https://kubernetes.io/ as a good example.

[alexander-yevsyukov]

Here's some info on arranging versioned Jekyll content with stable branches (or tags):

https://justwriteclick.com/2017/07/30/investigating-jekyll-for-versioned-content/

[alexander-yevsyukov]

@oleksandra-kovalenko, we'll need to answer this question in a couple of weeks. We'll need it for being able to release v2.

[JuliaEvseeva]

@alexander-yevsyukov, @oleksandra-kovalenko, @andreySadomovskiy.

After some investigation and searching for examples we suggest having each version in a sub-directory under the docs folder.
Thanks to Jekyll and Yaml variables, we can semi-automate this process. All we need to do is keep the previous version of the documentation in the appropriate folder, copy the navigation file, and adjust the _config.yml file. We will not need to edit links every time, this will be done automatically.

The structure will be:

_data
   ├── navigation
       ├── doc-side-nav-current.md
       └── doc-side-nav-1_0.md

docs
   ├── current
   └── 1.0

This approach with sub-directories is used in these examples:

• PyTorch
• Babel
• Gradle

The advantages of this method:

• clear structure;
• easy in implementation;
• the possibility to create the side navigation structure as we want;
• easy to maintain global website styles and components.

Other questions.

• We will be able to setup our search for each version (it will take some time from the Algolia guys to approve our request).
• If we want to change the code example for some version we should remember that maybe it has been already used in another version.

[alexander-yevsyukov]

Are there other approaches for doing this?

[JuliaEvseeva]

Another way to do this is to use branches for versioning. Here is the test repository that shows how it could be.
The cons of this method that they completely duplicate the entire site in each branch. For now, I don't understand how it will be built if we change some global styles in the version branch.
It is also not yet clear how to make a document side navigation. In the example, they use hardcode links.

Further, the site will still need to build in one branch (in the example it is a pg-pages), and the folders will be first copied from the branches to the root of the project, and then stored in the _site folder. But the structure will not be as clean as if we created it ourselves.