Releasing new documentation versions

The steps that are both necessary and recommended for updating the documentation to a new version are explained on this page.

Explaining by example: Releasing the SDK 4.0.0 docs

This guide uses the release of the SDK version 4.0.0 docs as an example to illustrate the general steps that need to be implemented for a new release on a practical level. Lisk SDK version 3.0.2 is the previous latest version in this example.

1. Preparing the new docs

1.1. Learning

Examples of how to acquire further knowledge about the new release:

1.2. Setting up a new project in the lisk-docs repository

  1. Create a new project on lisk-docs for the new version: https://github.com/LiskHQ/lisk-docs/projects

    • title: "Lisk SDK 4.0.0"

    • description: follow the existing examples

  2. Create issues for all upcoming content changes in the docs and add them to the project. New issues can still be added later, if necessary.

Major release

If a major version is released, a new content branch needs to be created for it.

Create a new branch docs-sdk-v3, on the base of docs-sdk. As the version number indicates, this branch will store the docs that become outdated with the new release.

On branch docs-sdk
git checkout docs-sdk
git pull origin docs-sdk
git checkout -b docs-sdk-3.0.2 (1)
git push origin docs-sdk-3.0.2 (2)
git checkout docs-sdk (3)
1 Switch to a new base branch for the SDK v3 docs.
2 Push the new content branch to the lisk-docs repository.
3 Go back to the docs-sdk branch.

The branch docs-sdk will be used as base for the new documentation. All issues created for the new version will be merged into this new branch.

To do so, bump the version in antora.yml:

On branch docs-sdk
name: lisk-sdk
title: Lisk SDK
version: 'v4' (1)
display_version: '4.0.0' (2)
start_page: ROOT:index.adoc
nav:
- modules/ROOT/nav.adoc
1 Bump to the latest version (v + 1 digit).
2 Change from master to the new version (3 digits SemVer). This will be changed back to master as one of the last steps before the new docs release.
During the creation of the SDK v4 documentation, the docs in docs-sdk-3.0.2 represent the latest version, therefore site.yml and live-site.yml in the build branch need to be updated accordingly.

2. Content creation

Please create the content according to the guide Contributing to the documentation and the Style guide for writing good documentation content.

The recommended order of updating the SDK docs is as follows:

  1. Navigation: Take a look at the navigation in the nav.adoc file, and adjust the structure for the new version. This will help you to get an overview about the upcoming changes, and to create tasks in the right scope.

  2. References

    1. Update API specification with swagger2markup

      cd framework-plugins/lisk-framework-http-api-plugin
swagger2markup convert -i ./swagger.yml -d ~/swagger-spec

      Then copy the content of the generated files and remove outdated links from the description.

    2. Update Lisk Commander reference

    3. Update Lisk Elements reference

    4. Update Lisk Framework reference

    5. Update Config reference

  3. Explanations

  4. Example applications

    These updates need to be done in the lisk-sdk-examples repository.

  5. Tutorials

  6. Guides

  7. Changelog

3. UI updates

  • Update the top navigation in src/partials/header-content.hbs:

    • Check, if any links are outdated, and then update or remove them as necessary.

    • Check, if any new links should be added.

    • If a new documentation component is released: The new component needs to be added in the top left side and shown dynamically.

4. Release preparations

4.1. Updates on docs-sdk-v3

Update antora.yml

This needs to be updated at the same time as on the latest version branch.

  • Create a new issue to update the version of the previous version branch in antora.yml.

  • Change master to v3.

  • Change 3.0.2 (latest) to 3.0.2.

Updates on other branches such as docs-core-3.0.0-beta.0

Do not forget to check if it is necessary to perform any updates in other components, which relate to references within the applicable pages.

Add versions in snippets

npm i lisk-sdk # before
npm i [email protected] # after

Perform this for all Lisk Elements packages and also Lisk Commander.

//before
:url_github_hello: https://github.com/LiskHQ/lisk-sdk-examples/tree/development/hello_world
//after
:url_github_hello: https://github.com/LiskHQ/lisk-sdk-examples/tree/development/archive/3.x/hello_world

4.2. Updates on docs-sdk

Update antora.yml

This needs to be updated at the same time as on the previous version branch.

  • Change v4 to master.

  • Change 4.0.0 to 4.0.0 (latest).

Check redirects

Check, if new page-aliases need to be added to the page attributes. This is the case in particular, if pages have been moved or removed in the latest version.

5. Release

5.1. Update the live playbook

before
content:
  sources:
  - url: https://github.com/LiskHQ/lisk-docs.git
    branches: [docs-core, docs-service, docs-protocol, docs-sdk-2.3.8, docs-sdk-3.0.2, docs-core-2.1.6]
after
content:
  sources:
  - url: https://github.com/LiskHQ/lisk-docs.git
    branches: [docs-core, docs-sdk, docs-service, docs-protocol, docs-sdk-2.3.8, docs-sdk-3.0.2, docs-core-2.1.6]

5.2. Building the new live documentation with Antora

On the build branch
source antora/.env
antora live-site.yml --fetch
cd live
git status
git add .
git commit -m "Update docs"
git push origin live

At this point, it is necessary to ask the Devops team to update the documentation on lisk.io. They will then deploy the new content and flush the cache.

5.3. Updating the search index

Ensure that Docker is started and that you are on branch build.

cd searchdocs-scraper

Firstly, ensure you have Docker running on your machine and that you can list images.

docker images

Then, pass the config file to the docsearch docker:run command, which launches the provided Docker container (algolia/docsearch-scraper):

pipenv run ./docsearch docker:run ./config.json

If that command succeeds, it means the index is now updated.

For more information about the setup and usage of the search index, check the guide Setting up docsearch.