Adding versioning to docs.

[rob3000]

This PR takes a first run at #279.

I currently only have the following versions:

• 1.12.0 (current)
• 1.11.0
• 1.10.0

I have a question around the tags, should i also be doing the minor updates docs as well e.g 1.9.0, 1.9.1, 1.9.2?

Not sure if we will need to look at adding in a job to azure-pipelines.yml to allow adding a versioned document based on a tag e.g: cd website && yarn run version ${TAG}

[Nevon]

Thanks for taking a stab at this. This is something that's been highly requested, and will reduce the number of incoming questions by quite a bit.

First, let's see if I understand Docusaurus versioning correctly.

• By running docusaurus-version <version> you create a new versioned set of docs, which essentially copies the contents of /docs into /website/versioned_docs/version-<version> and adds a reference in /pages/en/versions.json.
• Each version of the docs will be available at /docs/<version>/
• The last created version (regardless of the name of the version) will be available at /docs/ as well as /docs/<version>.
• The docs in master will be available at /docs/next/

If this is correct, then that seems good to me. One concern that I had was breaking existing links, but that shouldn't be the case since the current version will always be available at /docs/.

One thing that we'll need to address, probably, is how we generate URLs to the docs, since ideally we'd want to point to the docs for that version of KafkaJS, so we'll need to read that from the package.json. This does not need to be addressed within the scope of this PR, however.

kafkajs/src/utils/websiteUrl.js

Line 3 in 7d7a765

module.exports = (path, hash) => `${BASE_URL}/${path}${hash ? '#' + hash : ''}`

I have a question around the tags, should i also be doing the minor updates docs as well e.g 1.9.0, 1.9.1, 1.9.2?

Yes, I believe we should create a version whenever we create a new (stable) release, basically. It seems a lot simpler than trying to conditionally create versions only for minor and major releases. I don't think we should create versions for the beta releases. If you're using the beta version of the package, you can just rely on /docs/next.

However, I don't think you need to go back and create versions for all of those now. I'm perfectly fine with just having 0.12.0 and next for now.

Not sure if we will need to look at adding in a job to azure-pipelines.yml to allow adding a versioned document based on a tag e.g: cd website && yarn run version ${TAG}

That would be nice. I would say it's another job with similar conditions to the release job:

https://github.com/tulios/kafkajs/blob/master/azure-pipelines.yml#L211-L235

The steps would be similar to the website build, except that instead of invoking the Docusaurus "publish-to-gh-pages" action we would invoke the docusaurus-version action and then commit and push that back to master. It's a little tricky to get this right, especially since you won't have direct access to azure pipelines to test it out, so I would leave that part to us (I hear @tulios loves Azure Pipelines).

One thing you could do, however, would be to revert this commit, since it will no longer be necessary.

[rob3000]

Hey @Nevon,

By running docusaurus-version <version> you create a new versioned set of docs, which essentially copies the contents of /docs into /website/versioned_docs/version-<version> and adds a reference in /pages/en/versions.json

Correct.

Each version of the docs will be available at /docs//

Correct. And you can view all the versions by visiting /versions

The last created version (regardless of the name of the version) will be available at /docs/ as well as /docs/<version>.

Not really, the latest version will always be at /docs and wont be available at /docs/<version> until a newer version is published.

The docs in master will be available at /docs/next/

Correct.

That would be nice. I would say it's another job with similar conditions to the release job....

I thought as much :)

I'll revert that commit now as well.

[Nevon]

Let me know if there's anything else you want to address before we merge this.

[rob3000]

I think that's all from me 😄

[Nevon]

Then let's give it a whirl and see what happens.