Versioning of build section

[Dr-Electron]

With the introduction of Shimmer, a versioning system in the wiki became more and more important.

Here I will summarize what has been tested and which way we prefer with the current knowledge.

We started with our old build system. This made it much more difficult to implement versioning in general.
But with the new build system (#498) we have better possibilities.
Basically, there are two:

• The Docusaurus way
• The "roll our own versioning" way

Let's talk about both approaches.

The Docusaurus way

Docusaurus provides its own versioning system. It basically creates a copy of the docs in another folder.

Pros

• We rely on something already existing
• Nice features like marking docs as upcoming, stable or unmaintained

Cons

• We need to have everything in one repo or at least copy everything into one folder at build
• Some bugs in Docusaurus need to be solved first (for example refactor: fix a few places of path handling facebook/docusaurus#7023 and a lot of other problems like this were found on the way. Most are related to paths not getting resolved correctly in our system)
  • Docusaurus doesn't pick up versioning if the versioned folder is a subfolder (probably same problem as in above example. Docusaurus again doesn't resolve path relative to the sub config)
• We can't specify custom paths to versioned docs. So we would need some copy magic on build to build the structure wanted by Docusaurus ourselves.

The "role our own versioning" way

With the new build system, we would build a structure like mentioned in #498
As an example for Hornet:

hornet/
├── develop/
│   └── documentation/
│       ├── docs
│       ├── docusaurus.config.js
│       └── sidebars.js
├── staging/
│   └── documentation/
│       ├── docs
│       ├── docusaurus.config.js
│       └── sidebars.js
└── production/
    └── documentation/
        ├── docs
        ├── docusaurus.config.js
        └── sidebars.js

So every subfolder is a git submodule of a specific branch.
We would then build a dropdown which checks the existing path and let you switch between them.

Example paths could be:

hornet/welcome
hornet/staging/welcome
hornet/develop/welcome

Pros

• We keep using our new nice and clean build system
• Versioned docs are separated by branches and not in the same repo
• Even without the dropdown, we can easily implement this by having a "shimmer" section in the mega menu
• We are in control of the whole logic

Cons

• We are in control of the whole logic
• Merging may be a bit more involved. (Every Docusaurus config may need its own ID and specific "baseRoute" which always need to stay on the same branch)

Conclusion

We probably could convince Docusaurus to change some of their stuff, as it wouldn't be too much work and would fit into their logic (and most problems are bugs on their side anyway ). But as I think we don't want to have all docs in a single repo, we would always need to split it into multiple submodules.
So imo we should go the The "roll our own versioning" way :trollface: because then if we can convince Docusaurus later on into adapting their system (with for example customizable paths to different versions) we can just change our dropdown for theirs basically

[jlvandenhout]

I agree on the versioning by branches. This makes most sense from a project maintainer perspective and allows us to utilize the new build system fully.

Each branch of a project would then contain its own version of the documentation, with a Docusaurus config defining any plugins it needs. Then on the Wiki side we will have a directory containing:

• Subdirectories for each branch of the project we want to expose
• A Docusaurus config containing a custom versioning plugin that registers the versions contained in the subdirectories.

The versioning plugin takes care of placing the default version on a default path (mimicking the Docusaurus plugin, i.e. /hornet) and any other versions on a version specific path (i.e. /hornet/develop, /hornet/staging, etc). As sidebars are part of the docs plugin, this should be taken care of automatically.

Then we can provide a dropdown component similar to the versioning dropdown of Docusaurus that lists the versions available for the current path.

[jlvandenhout]

Just to keep notes:

• The plan is to have a parent config that lists the to be versioned child configs.
• The parent config mutates the plugins contained in all the child configs, except one (which is configured as default config version).
• Only the plugin id and possible basePaths should have to be mutated to prevent duplication of routes or plugins, the rest should be relative to the child configs so should work out of the box.
• We will have a version component that knows when to give options to choose different versions.

Open questions:

1. Where do we want to place the version component? I guess in the navbar like the Docusaurus version component? Other options are in the doc page, in the sidebar, etc. but those might not be visible all the time.
2. Do we want version or project first in the basepath? I guess version first, as we will have different versions of learn docs as well? And later on even languages maybe.
3. How are we going to version? Per route? Per plugin? etc. And how are we going to let the version component know what to show?

[Dr-Electron]

1. I think a dropdown in the navbar is the easiest and best solution.
   Dyte does it in the sidebar. Just for reference.
2. I think project should be first. As versions will/could be different for different projects.
3. Isn't per route and per plugin basically the same?

[Dr-Electron]

So, initially I expected that you could somehow specify in .gitmodules if you want to update the submodule (--remote) or keep the current commit. But even if that would possible with !command for the update property, it would still not work as it's only allowed in .git/config.
So I want to propose some different solutions. Keep in mind that I didn't test them yet:

1. Maintain a different script/config which goes through every submodule and decides if it should do a update or update --remote
2. Split submodules into track branch or track commit and use the two different update commands for them.
3. Don't update the submodules and create an action in the submodule repo to update the commit in the wiki on change.
4. Use Docusaurus versioning for specific versions. We could let our plugin check if versioning exists and include that in our dropdown. It's a little bit hacky tho

I think I prefer 1) because it doesn't change the layout and isn't too complicated to implement with the cli

[Dr-Electron]

Let's call 1 branch versioning, as a version represents the latest state of a branch of documentation, and 2 release versioning, as a version represents the state of documentation at a specific point in release history.

Love it 👍

An open question I believe is how to clearly distinguish between the two in the UI. I think simply adding a label to the respective version dropdowns already would help a lot, something like "network version" and "project version" for example. Maybe the UX team can help here.

This also depends on the need of the projects. Are they ever going to mix both versions? If so, I would have just simply gone with the following structure in the dropdown (yes, i want a single dropdown 😆 )

branch-version

We could even split the dropdown in subsections like Docusaurus does in their version dropdown:

production-0.1.0
production-0.2.0
-----------------
staging-0.3.0
-----------------
develop

[jlvandenhout]

Makes total sense to me too actually. I still struggle a bit with the branch versioning without explanation. I've experienced this with the Ethereum docs as well for example, it is really difficult to guess right off the bet what version you are supposed to be looking at, unless you already read somewhere else about the different networks and their purpose.

So expanding on your idea of the single dropdown, what about having sections per branch version and make the section header clickable or add an information icon that is clickable and link to the relevant introductory docs (when available of course)?

[Dr-Electron]

Sure. Let's add it at the end of our to-do

[Dr-Electron]

But being serious, we need some kind of config for that in our plugin. Because not every project may need branch versioning for IOTA and Shimmer. Maybe the just want it for the main and develop branch or something like that 🤔

[Dr-Electron]

For now we went with branch versioning. Because release versioning doesn't really work if you need to reference/import something from outside the documentation folder like examples for example ;)