Page Comparison

For the Besu documentation repositories, a A new stable version of the Besu documentation is released when a new version of the Besu software is released.

The process consists of one manual action and two automatically triggered actions:

1. Manually create a release on GitHub

When a new version of the software is released, the documentation team manually creates a release on the corresponding GitHub documentation repository.

Documentation versioning follows the same Calendar Versioning (CalVer) pattern as the software to help users match the documentation version to the software version easily.

The GitHub release creation process tags the Git repository with the new version (for example, 21.1.4).

2. Automatically build the documentation on RTD

When Read the Docs (RTD) detects a new tag on a documentation repository, RTD automatically generates the following documentation versions:

• Latest - Corresponds to the latest commit in the main branch of the documentation repository.
• CalVer - Corresponds to the tag in the main branch that was created during the release (for example, 21.1.4).
• Stable - Corresponds to the last created tag.

RTD builds all three versions, all showing the same content from the same commit.

As contributors continue to work on the documentation, RTD rebuilds the latest version from the latest main commit each time a new PR is merged, and the CalVer and stable versions remain behind latest.

Note: The Besu documentation repository default branch is now named main.

3. Automatically activate the documentation version on RTD

...

NOTE: If it's the first time (or if any dependencies have changed), you will need to run yarn install to install Docusaurus

You 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:

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.

For example, when updating from version 23.4.1  to 23.4.2 , update the following section in docusaurus.config.js  from the following:

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:

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