Support Docusaurus versioning

[richardwerkman]

Docusaurus supports versioning like this:

https://docusaurus.io/docs/versioning

I expect we cannot use this at the moment since every stryker has its own version. So idealy we would be able to select different versions depending on which stryker (js/net/scala) you are seeing the docs from.

I don't know if this is possible out of the box with docusaurus. If not we might be able to think of our own solution like using a global vCurrent and vNext . Or just version using a different technique without the docusaurus selector.

[hugo-vrijswijk]

I think this would be a very nice feature. For Stryker4s, there's been some confusion about what config option was introduced in which version, though we've now 'solved' that by adding a since to each config option.

I don't think it'd work out of the box with Docusaurus. It expects 1 set of docs of the whole site per version. Which works best if there's 1 project that you want to make versioned docs for. We could make some sort of script to get the docs of each Stryker repo per the last x tags, but then what version do you use for Stryker-JS if you're looking at the version Stryker4s-v0.13.0? Whatever it is the script or setup probably won't be super simple.

If we go for this, we should also follow some of the best practices mentioned on Docusaurus. Namely, the 'current' always being the latest (untagged) version of the docs, and not having too many versions per framework (5 per framework sounds reasonable to me).

[richardwerkman]

I think it might be possible after all. Look at page: https://docusaurus.io/docs/docs-multi-instance
Docusaurus says they have multiple instances themselves. One instance is versioned. Another is not. So it might be possible to have multiple instances that are all versioned?

[rouke-broersma]

At worst we can use a 'current' and a 'vnext' instead of specific version numbers. This should cover most use cases and should be applicable to all of us.

[nicojs]

I have mixed feelings about this. Sure it is nice for people that are looking for a specific version. However, I see a couple of disadvantages.

1. If you're on an older version, you should probably upgrade to the latest version. Using 1 set of docs with a since might entice users to migrate sooner, because they would more easily spot new features.
2. There are a lot of reasons to update the docs besides new features or breaking changes. I think that about 80% of changes in the stryker-js docs are general documentation improvements. They are also relevant for older versions. However, I don't want to have the burden of updating the same text in a lot of documents 🤷‍♀️

With that being said, we can still move forward with this change as long as it is optional per Stryker framework.

[rouke-broersma]

@nicojs The biggest issue is that currently the website often has docs that are not yet valid, because we have not yet released a new stryker version. Because of this we created a long living branch for our v1 release but this has once again proven that long living branches are a mistake. We don't want to have to make this mistake in the future, and thus we need at least 2 sets of docs (current and vnext).