How to Version Docs

Prerequisites

Read Docusaurus Versioning.

Workflow

Before you proceed, make sure you have comit-js-sdk and comit.network repos in the same directory on your machine:

.
├──work/
|   ├── comit-js-sdk/ ~ tag 0.15.2
|   └── comit.network/
           └── docs/
                 └── comit-sdk/ # Generated Docs
           └── versioned_docs/  
                 └── version-0.15.2/    # Generated Folder
                         └── comit-sdk/ # Generated Docs

• Only modify files in docs/. You can create new .md files or modify existing files.
  • Avoid modifying versioned_docs/ directly.
  • Instead, use the yarn docusaurus docs:version command explained in Publishing as a New Version
• In comit.network/, regenerate SDK docs by running yarn build:sdk.
  • This command uses the comit-js-sdk repo version on your machine e.g. master or 0.15.2.
  • This command will automatically generate SDK docs of comit-js-sdk and update the website files.
• Commit and push your changes. Merge it.
  • Your changes won't be viewable in https://comit.network/docs/, but it will be in https://comit.network/docs/next/.

Publishing as a New Version

• To publish your changes, run yarn docusaurus docs:version <your NEW version e.g. 0.15.3>.
  • The above command will create a new version-0.15.3 folder in versioned_docs/ and version-0.15.3-sidebars.json in versioned_sidebars. Think of these files as versioned snapshots of the documentation.
• Commit and push your changes. Merge.
  • The new version will be viewable on https://comit.network/docs/ as the default version.
  • The website is automatically redeployed whenever master is updated.

Publishing as an Existing Version

You want to update the documentation for an existing version in versioned_docs/version-0.15.2.

Check that the comit-sdk folder in docs is generated for the version you want to re-generate (0.15.2 in this example) before you re-generate it. You can do so by checking the commit-hash used in file-links in files the comit-sdk folder. For 0.15.2 the commit is ee6360f as one can see from the release page.

If the comit-sdk version points to the correct version (i.e. the hash is correct) you can just generate the version again:

• Remove the version string (e.g. e.g. 0.15.2) you want to overwrite in versions.json.
• Then, run yarn docusaurus docs:version 0.15.2.

If the comit-sdk in docs does not point to the SDK version you want to update, then you should reset the comit-sdk in docs to that version before re-generating the version (i.e. 0.15.2). Follow the steps below to do so.

• First, make sure you have the comit-js-sdk checked out to the existing version and not master.

.
├──work/
|   ├── comit-js-sdk/ ~ tag 0.15.2
|   └── comit.network/
           └── docs/
                 └── comit-sdk/ # Generated Docs
           └── versioned_docs/  
                 └── version-0.15.2/    # Generated Folder
                         └── comit-sdk/ # Generated Docs

• In comit.network/, regenerate SDK docs by running yarn build:sdk.
  • This step ensures that the current comit-sdk/ in docs/ does not overwrite the folder in the existing version. Instead, we use the same comit-sdk/ version.
• Remove the version string (e.g. e.g. 0.15.2) you want to overwrite in versions.json.
• Then, run yarn docusaurus docs:version 0.15.2.