docs: add docs section to RELEASE_PROCESS.md (#1976)

* docs: add docs section to RELEASE_PROCESS.md * docs: update the release notes template
cosmos · Jun 20, 2024 · 060c943 · 060c943
1 parent 1c09021
commit 060c943
Show file tree

Hide file tree

Showing 2 changed files with 73 additions and 1 deletion.
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -17,7 +17,7 @@
 ** REMOVE THE LINE BELOW TO ENABLE THE MARKDOWN LINK CHECKER FOR RELEASE **
 <!-- markdown-link-check-disable -->
 
-Check out the [changelog](https://github.com/cosmos/interchain-security/blob/<v*.*.*>/CHANGELOG.md) for a list of relevant changes or [compare all changes](https://github.com/cosmos/interchain-security/compare/release/<v-last>...<v*.*.*>) from last release.
+Check out the [changelog](https://github.com/cosmos/interchain-security/blob/<v*.*.*>/CHANGELOG.md) for a list of relevant changes or [compare all changes](https://github.com/cosmos/interchain-security/compare/<v-last>...<v*.*.*>) from last release.
 
 <!-- Add the following line for major or minor releases -->
 Refer to the [upgrading guide](https://github.com/cosmos/interchain-security/blob/release/<v*.x>/UPGRADING.md) when migrating from `<v-last.x>` to `<v*.x>`.

diff --git a/RELEASE_PROCESS.md b/RELEASE_PROCESS.md
@@ -107,6 +107,78 @@ Once the **final release** is cut, the new changelog section must be added to ma
     ```
 - open a PR (from this new created branch) against `main`
 
+## Updating published docs
+
+### Before tagging a new release
+
+On your release branch, clear the `docs/versions.json` file so it looks like this:
+```json
+[]
+```
+
+If this file is populated on a release branch it will cause the tag to have extra files that the docs deploy process does not expect. This could cause the deploy process to fail in some situations.
+
+### After tagging a new release
+
+Go to `main` branch and update the `docs/versions.json` to include all the versions you want to publish on the docs page:
+```json
+[
+    "v4.3.0",
+    "v5.0.0"
+]
+```
+
+This will cause the docs to be built with `main`, `v4.3.0` and `v5.0.0`.
+
+In `docs/docusaurus.config.js` change the `preset` section to display the versions you chose in `docs/versions.json`.
+
+For example, here we remove v4.2.0 and replace it with v4.3.0.
+
+```diff
+  presets: [
+    [
+      "classic",
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve("./sidebars.js"),
+          routeBasePath: "/",
+          versions: {
+            current: {
+              path: "/",
+              label: "main",
+              banner: "unreleased",
+            },
+            // v4.2.0-docs was a special tags for docs
+            // this is not usually necessary
+-            "v4.2.0-docs": {
+-              path: "/v4.2.0/",
+-              label: "v4.2.0",
+-              banner: "none",
+-            },
++            "v4.3.0": {
++              banner: "none",
++            },
+            "v5.0.0": {
+              banner: "unreleased",
+            },
+          },
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+        },
+
+        theme: {
+          customCss: require.resolve("./src/css/custom.css"),
+        },
+      }),
+    ],
+  ],
+```
+
+The documentation is updated automatically whenever `main` is changed.
+
+To learn how to work with docs locally check the docs [README.md on main branch](https://github.com/cosmos/interchain-security/blob/main/docs/README.md)
+
 ## Tagging Procedure
 
 **Important**: _**Always create tags from your local machine**_ since all release