Merge pull request #6 from Consensys/addReleaseProcess

Add release process for versioned docs.
Consensys · Aug 28, 2023 · 8fa1899 · 8fa1899 · vercel · Aug 28, 2023
2 parents 77315b3 + f818537
commit 8fa1899
Show file tree

Hide file tree

Showing 6 changed files with 381 additions and 29 deletions.
diff --git a/docs/configure/search.md b/docs/configure/search.md
@@ -18,7 +18,7 @@ the conditions as long as the docs are open source.
 This page contains instructions for configuring Algolia for both [open-source](#docs-and-source-code-are-open-source)
 and [closed-source](#source-code-is-not-open-source) projects.
 
-## Docs and source code are open source
+## For an open source codebase
 
 Follow these steps to configure Algolia in your project:
 
@@ -50,7 +50,7 @@ Follow these steps to configure Algolia in your project:
    Edit the `docs` index in the file to match your repository's index in Algolia.
    This workflow runs in the background and populates the index that Algolia uses to search.
 
-## Source code is not open source
+## For a close source code base
 
 If your project doesn't satisfy the [Algolia checklist](https://docsearch.algolia.com/docs/who-can-apply/),
 then you can't use Algolia for free.

diff --git a/docs/configure/versioning/index.md b/docs/configure/versioning/index.md
@@ -3,28 +3,161 @@ description: Support and manage multiple documentation versions.
 sidebar_position: 1
 ---
 
-# Configure versioning
+# Configure and use versioning
 
 Docusaurus can manage multiple versions of your documentation.
 See the [Docusaurus versioning documentation](https://docusaurus.io/docs/next/versioning) for
 detailed context and instructions on managing versions.
 
-## Create a docs version
+The following instructions are for documentation that uses n versions that can be accessed like so:
+
+| Path	                               | Version        | URL                | 
+|:-----------------------------------  |:-------------  |:-------------------|
+|versioned_docs/version-0.x/hello.md   | 0.x	          | /0.x/hello        |
+|versioned_docs/version-1.0/hello.md   | 1.0 (latest)   |	/hello             |
+|docs/hello.md	                       | development    |	/development/hello |
+
+:::info
+Please note that unlike Read the Docs (RTD) that versions by tags on the code base, in Docusaurus,
+every version in history is kept in the `versioned_docs` folder, so the onus is on you to remove
+older versions when required
+:::
+
+Docusaurus nomenclature is slightly different to what we use. In docusaurus, all actual versions
+are referred to by name and are sub folders in `versioned_docs`; and the next version is therefore called
+`next` (the next version). In Consensys we follow the same for the `versioned_docs` but use the
+term `development` instead, and this can be configured in docusaurus.config.js like so, where
+the `current` version is given a `label` and `path` attribute.
+
+```js
+...
+    routeBasePath: "/",
+    path: "./docs",
+    includeCurrentVersion: true,
+    lastVersion: "1.0",
+    versions: {
+      //defaults to the ./docs folder
+      // using 'development' instead of 'next' as path
+      current: {
+        label: "development",
+        path: "development",
+      },
+      //the last stable release in the versioned_docs/version-stable
+      "1.0": {
+        label: "1.0",
+      },
+      "0.x": {
+        label: "0.x",
+      },
+    },
+...
+```
+
+## Release a new docs version
+
+### 1. Create a new version of the documentation:
 
-Release version 1.0 of your docs using the following command:
+In the following steps, we'll release the `1.0` version of the documentation (`./docs`) as an example.
+
+<!--tabs-->
+
+# Syntax
+
+```bash
+npm run docusaurus docs:version <VERSION-NUMBER>
+```
+
+This command:
+
+- Copies the full `docs/` directory into a new `version-<VERSION-NUMBER>` directory in the `versioned_docs` directory.
+- Creates a new `versioned_sidebars/version-<VERSION-NUMBER>-sidebars.json` file.
+- Appends the new version number to the `versions.json` file.
+
+# Example
 
 ```bash
 npm run docusaurus docs:version 1.0
 ```
 
-The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
+This command:
+
+- Copies the full `docs/` directory into a new `version-1.0` directory in the `versioned_docs` directory.
+- Creates a new `versioned_sidebars/version-1.0-sidebars.json` file.
+- Appends the new version number to the `versions.json` file.
+
+<!--/tabs-->
 
 Your docs now have two versions:
 
-- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
-- `current` at `http://localhost:3000/docs/next/` for the upcoming, unreleased docs.
+- `1.0` at `http://localhost:3000/` for the version 1.0 docs
+- `current` at `http://localhost:3000/next/` for the upcoming, unreleased docs.
+
+### 2. Update the `docusaurus.config.js` file to re-label these paths
+
+In `docusaurus.config.js`, under `presets` > `classic` > `docs`:
+
+- Update the `lastVersion` to the new version number.
+- Under `versions`, update the current version to the new version.
+
+For example, when releasing version `1.0`, update the following section in the `docusaurus.config.js`
+file by updating the version number:
+
+```js
+presets: [
+  [
+    "classic",
+    {
+      docs: {
+        sidebarPath: require.resolve("./sidebars.js"),
+        // Set a base path separate from default /docs
+        editUrl: "https://github.com/ConsenSys/doc.teku/tree/master/",
+        routeBasePath: "/",
+        path: "./docs",
+        includeCurrentVersion: true,
+        // highlight-next-line
+        lastVersion: "1.0",
+        versions: {
+          //defaults to the ./docs folder
+          // using 'development' instead of 'next' as path
+          current: {
+            label: "development",
+            path: "development",
+          },
+          //the last stable release in the versioned_docs/version-1.0
+          // highlight-start
+          "1.0": {
+            label: "1.0",
+          },
+          // highlight-end
+        },
+...
+],
+
+```
+
+### 3. Update the `versions.json` file
+
+:::info
+Please remember to remove any old versions that you are not required in this file
+:::
+
+```json
+[
+  "1.0",
+  "0.x"
+]
+```
+
+### 4. Delete the previous doc versions (if needed)
+
+If you have deleted a version in step 3, also delete the artifacts for that version. For example, if deleting version `0.2` that would mean deleting the following:
+
+1. In the `versioned_docs` directory, delete the `version-0.2` folder
+2. In the `versioned_sidebars` directory, delete the `version-0.2-sidebars.json` file.
+
+Create your pull request. You can perform a final check using the preview link generated for your PR.
 
-## Add a version dropdown
+### 5. Add a version dropdown (Do this once only when versioning is introduced)
 
 To navigate seamlessly across versions, add a version dropdown by modifying `docusaurus.config.js`
 as follows:
@@ -58,4 +191,4 @@ The docs version dropdown appears in your navbar:
 You can edit versioned docs in their respective folder:
 
 - `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`.
-- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`.
+- `docs/hello.md` updates `http://localhost:3000/docs/development/hello`.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -93,7 +93,24 @@ const config = {
           // Set a base path separate from default /docs
           editUrl: "https://github.com/ConsenSys/docs-template/tree/main/",
           routeBasePath: "/",
-          path: "docs",
+          path: "./docs",
+          includeCurrentVersion: true,
+          // lastVersion: "23.x",
+          // versions: {
+          //   //defaults to the ./docs folder
+          //   // using 'development' instead of 'next' as path
+          //   current: {
+          //     label: "development",
+          //     path: "development",
+          //   },
+          //   //the last stable release in the versioned_docs/version-stable
+          //   "23.x": {
+          //     label: "stable (23.x)",
+          //   },
+          //   "22.x": {
+          //     label: "22.x",
+          //   },
+          // },
           // @ts-ignore
           // eslint-disable-next-line global-require
           remarkPlugins: [require("remark-docusaurus-tabs")],
@@ -108,7 +125,6 @@ const config = {
           ],
           showLastUpdateAuthor: true,
           showLastUpdateTime: true,
-          includeCurrentVersion: true,
         },
         theme: {
           customCss: require.resolve("./src/css/custom.css"),
@@ -275,21 +291,6 @@ const config = {
           language: "nodejs",
           logoClass: "nodejs",
         },
-        // {
-        //  highlight: "ruby",
-        //  language: "ruby",
-        //  logoClass: "ruby",
-        // },
-        // {
-        //   highlight: "csharp",
-        //   language: "csharp",
-        //   logoClass: "csharp",
-        // },
-        // {
-        //   highlight: "php",
-        //   language: "php",
-        //   logoClass: "php",
-        // },
       ],
     }),
   plugins: [
@@ -306,8 +307,33 @@ const config = {
         containerId: "GTM-",
       },
     ],
-  ], // remove if not using docusaurus-plugin-openapi-docs
-  themes: [], // remove if not using docusaurus-plugin-openapi-docs
+    // This is how redirects are done
+    // [
+    //   "@docusaurus/plugin-client-redirects",
+    //   {
+    //     redirects: [
+    //       {
+    //         from: "/HowTo/Get-Started/Installation-Options/Install-Binaries",
+    //         to: "/get-started/install/install-binaries",
+    //       },
+    //     ],
+    //     // its quite odd here in that its back to front - replace(to, from)
+    //     createRedirects(existingPath) {
+    //       if (existingPath.includes("/development")) {
+    //         return [
+    //           existingPath.replace("/development", "/en/latest"),
+    //           existingPath.replace("/development", "/latest"),
+    //         ];
+    //       }
+    //       if (existingPath.includes("/")) {
+    //         return [existingPath.replace("/", "/stable")];
+    //       }
+    //       return undefined; // Return a falsy value: no redirect created
+    //     },
+    //   },
+    // ],
+  ],
+  themes: [],
 };
 
 module.exports = config;