Releasing a A new stable version of the Besu documentation is to be done when the software new version released when a new version of the Besu software is released.
The process is composed of 1 manual action and 2 automatically triggered actions:
- Manually create a release on Github.
- Automatically build the newly released doc.
- Automatically activate newly released doc version.
Github repository release manual actions
Documentation versioning follows the exact same Calendar Versioning (CalVer) pattern as the software to enable users to find the documentation matching their software version easily.
This is done by creating a release on the Github documentation repository : https://github.com/hyperledger/besu-docs/releases
The Github release creation process creates a tag in the Git repository and a Github release that will trigger the build of the new documentation version on Besu Read The Docs project.
This part must be done manually by the release team.
Read The Docs automatic webhook triggered build
Read The Docs (RTD) will generate the following versions when a new tag is detected on the repository:
- Latest: corresponds to the latest commit in the master branch of the doc repos
- CalVer version (for example: "21.1.4"): corresponds to the tag in the master tat was created during the release
- Stable: corresponds to the last created tag (for example 21.1.4)
When creating a release, RTD will build 3 versions : latest, CalVer version and stable and they will all show the same content from the same commit.
But then when contributors will continue to work on the doc, the latest will be rebuilt from the latest master commit each time a new PR is merged and the CalVer version and stable will be behind latest.
Read The Docs version automatic activation
By default, new doc CalVer version are not activated by RTD, but we have a setup that tells RTD to activate CalVer numbered versions automatically once built: https://readthedocs.org/dashboard/hyperledger-besu/rules/
NOTE: If it's the first time, you will need to run
yarn install
to install DocusaurusYou will need
node.js
version v18.x (use NVM to easily manage node versions).
To release the documentation, first run the following command to create a new doc version:
Code Block | ||
---|---|---|
| ||
npm run docusaurus docs:version <VERSION-NUMBER> |
(This automatically updates versions.json
file to include the new version number.)
Then, in docusaurus.config.js
, under presets > classic > docs
:
- Update the
lastVersion
to the new version number.
- Under
versions
:- Add the new version and set its label to
stable (<VERSION-NUMBER>)
. - Update the previous version to remove the
stable
label.
- Add the new version and set its label to
For example, when updating from version 23.4.1
to 23.4.2
, update the following section in docusaurus.config.js
from the following:
Code Block | ||||
---|---|---|---|---|
| ||||
lastVersion: "23.4.1",
versions: {
current: {
label: "development",
path: "development",
},
"23.4.1": {
label: "stable (23.4.1)",
},
"23.4.0": {
label: "23.4.0",
},
}, |
To the following:
Code Block | ||||
---|---|---|---|---|
| ||||
lastVersion: "23.4.2",
versions: {
current: {
label: "development",
path: "development",
},
"23.4.2": {
label: "stable (23.4.2)",
},
"23.4.1": {
label: "23.4.1",
},
"23.4.0": {
label: "23.4.0",
},
}, |
commit your changes and push a PR to the besu-docs repo eg https://github.com/hyperledger/besu-docs/pull/1382
When this PR is merged to main, it should trigger a github action which will update https://besu.hyperledger.org/
The final step is to draft and publish a new release including the changelog on github: https://github.com/hyperledger/besu-docs/releases
...