chore: released docs versioning

* ci: added logic for creating new versions through a bash script * ci: added script to update docusarus config file programmatically * chore: update script * ci: updated versions script * ci: updated versions script * chore: script update * chore: save * chore:save * save * save * save * save * save * save * sve * save * save * save * save * chore: updates to script * save * docs: save * save * save * save * save * chore: script updates * save * save * save * save * save * save * save * save * save * save * save * save * save * save * ci: added versioning logic * ci: update temp folder for Netlify * ci: netlify debug * ci: updated versions script * ci: added output * ci: start build * ci: more netlify debug * ci: debug-netlify-2 * ci: netlify-3 * chore: netlify-4 * ci: netlify-5 * ci: netlify-6 * ci: netlify-6 * ci: netlify-7 * ci: netlify-7 * ci: netlify-8 * ci: netlify-9 * ci: netlify-11 * ci: netlify-12 * ci: netlify-12 * ci: netlify-13 * ci: netlify-14 * ci: netlify-15 * ci: netlify-16 * ci: netlify-17 * ci: netlify-18 * ci: netlify-19 * ci: netlify-20 * ci: netlify-21 * ci: preview versioning * ci: preview versioning * ci: preview versioning-3 * ci: preview versioning-3 * ci: preview versioning-3 * ci: preview versioning-3 * ci: preview versioning-3 * ci: preview versioning-5 * save * save * save * save * save * ci: preview versioning-6 * ci: new logic * ci: netlify error fix * ci: netlify working-2 * ci: netlify test * save * ci: netlify * ci: netlify part1 * ci: netlify part2 * ci: netlify part 3 * save * save * ci: netlify part 3 * chore: minor update * Document serviceDomain parameter in k8s config: PCP-935 (#1527) * Added serviceDomain to first tab only * Add serviceDomain to all version tabs * Removed breaks as needed, indented yaml * Fixed typo * Removed unneeded 'the' before link. * chore: removed version-3-4 * chore: debug * save * save * docs: updated readme * chore: eks-d redirect * chore: versioning working * docs: updated readme * ci: test netlify local builds * ci: netlify tests * ci: update netlify build * ci: netlify test 5 * ci: netlify 6 * ci: updated netlify * ci: save * ci: more netlify changes * ci: more netlify changes * ci: more netlify changes * ci: more netlify changes * ci: more netlify changes * ci: more netlify changes * ci: more netlify changes * ci: PR comment updates * ci: PR comment updates * ci: PR comment updates * ci: updated ci workflow * ci: test self-hosted runner * ci: install netlify * ci: netlify ci * ci: netlify * docs: updated readme * ci: testing large runners * ci: testing large runners * ci: testing large runners * ci: ci runner update * docs: save ci * chore: save * ci: removed CI build step for test * ci: save * ci: save (cherry picked from commit e2ef3ff)
spectrocloud · Sep 17, 2023 · 8c41f81 · 8c41f81
1 parent c536dbd
commit 8c41f81
Show file tree

Hide file tree

Showing 21 changed files with 58,101 additions and 27,608 deletions.
diff --git a/.backportrc.json b/.backportrc.json
@@ -3,7 +3,7 @@
   "repoName": "librarium",
   "editor": "code",
 
-  "targetBranchChoices": ["master", "version-4-0", "version-3-4", "version-3-3"],
+  "targetBranchChoices": ["master", "version-4-0", "version-3-4"],
 
   "autoMerge": true,
   "autoMergeMethod": "squash",

diff --git a/.github/workflows/aloglia_crawler.yaml b/.github/workflows/aloglia_crawler.yaml
@@ -2,15 +2,18 @@ name: Algolia Crawler
 
 on:
   workflow_run:
-    workflows: [Release to Production]
+    workflows: ["Release to Production"]
     types: [completed]
 jobs:
   docsearch:
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
+
       - name: Run scraper
         env:
           APPLICATION_ID: ${{ secrets.ALGOLIA_APP_ID }}
@@ -25,4 +28,4 @@ jobs:
           SLACK_USERNAME: "spectromate"
           SLACK_ICON_EMOJI: ":robot_panic:"
           SLACK_COLOR: ${{ job.status }}
-          SLACK_MESSAGE: 'The Docs Algolia crawler cron job failed. Please check the GitHub Actions logs for more details.'
+          SLACK_MESSAGE: 'The Docs Algolia crawler job failed. Please check the GitHub Actions logs for more details.'
diff --git a/.github/workflows/eslint-test.yaml b/.github/workflows/eslint-test.yaml
@@ -23,7 +23,9 @@ jobs:
   build:
     name: Build
     needs: [run-ci]
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
     if: ${{ !github.event.pull_request.draft }}
     steps:
       - name: Checkout Repository

diff --git a/.github/workflows/image_optimizer.yaml b/.github/workflows/image_optimizer.yaml
@@ -28,7 +28,9 @@ jobs:
   image-optimizer:
     name: Image Optimization
     needs: [run-ci]
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
     if: ${{ !github.event.pull_request.draft }}
     steps:
       - name: Checkout Repository

diff --git a/.github/workflows/pull_request.yaml b/.github/workflows/pull_request.yaml
@@ -55,8 +55,9 @@ jobs:
   build:
     name: Build
     needs: [run-ci]
-    runs-on: ubuntu-latest
-    # runs-on: [self-hosted, linux, x64]
+    runs-on: 
+      group: Default
+      labels: docbot
     if: ${{ !github.event.pull_request.draft }}
     steps:
       - name: Checkout Repository

diff --git a/.github/workflows/release-preview.yaml b/.github/workflows/release-preview.yaml
@@ -25,7 +25,9 @@ concurrency:
 jobs:
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
 
     steps:
       - name: Check out repository

diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -1,8 +1,15 @@
 name: Release to Production
 
+# Run this workflow every time a new commit is pushed to the master branch
+# or when a workflow run from the Version Branch Update workflow completes.
+# In either case, the branch used for the build will be master.
+
 on:
   push:
     branches: [master]
+  workflow_run:
+    workflows: [Version Branch Update]
+    types: [completed]
 
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -19,13 +26,19 @@ env:
 jobs:
   build:
     name: Build Website
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: "master"
+
 
       - name: Setup Node.js environment
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v
         with:
           node-version: "18"
           cache: "npm"
@@ -34,6 +47,7 @@ jobs:
 
       - name: Compile
         run: |
+          make versions-ci
           make build
 
       - name: Upload to AWS

diff --git a/.github/workflows/url-checks.yaml b/.github/workflows/url-checks.yaml
@@ -11,7 +11,9 @@ concurrency:
 name: Broken URL check
 jobs:
   markdown-link-check:
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
     steps:
       - id: checkout
         name: Checkout Repository

diff --git a/.github/workflows/version-branch-update.yaml b/.github/workflows/version-branch-update.yaml
@@ -22,12 +22,17 @@ env:
   ALGOLIA_ADMIN_KEY: ${{ secrets.ALGOLIA_ADMIN_KEY }}
   ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
   ALGOLIA_SEARCH_KEY: ${{ secrets.ALGOLIA_SEARCH_KEY }}
+  NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+  NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
 
 
 jobs:
   build:
     name: Build
-    runs-on: ubuntu-latest
+    runs-on: 
+      group: Default
+      labels: docbot
+
 
     steps:
     - name: Check out repository
@@ -41,10 +46,37 @@ jobs:
         node-version: '18'
         cache: 'npm'
 
-
     - run: npm ci
 
+    - name: Post Netlify progress
+      uses: mshick/add-pr-comment@v2
+      with:
+        message: |
+            🤖 Starting the Netlify preview build for commit ${{ github.sha }}. This may take a few minutes.
+        refresh-message-position: true
+        update-only: true
 
-    - name: Build
+    - name: Netlify Build
       run: |
-        make build
+        netlify build --context deploy-preview
+
+
+    - name: Deploy to Netlify
+      id: netlify
+      uses: nwtgck/actions-netlify@v2.1.0
+      with:
+        publish-dir: ./build
+        deploy-message: 'Manual Netlify deployment from GitHub Actions -  ${{ github.sha }}'
+        enable-pull-request-comment: true
+        overwrites-pull-request-comment: true
+        enable-commit-comment: true
+
+    - name: Post Netlify URL
+      uses: mshick/add-pr-comment@v2
+      with:
+        message: |
+            🚀 Netlify preview deployed succesfully for commit ${{ github.sha }}. Click [here](${{steps.netlify.outputs.deploy-url}}) to preview the changes.
+        message-failure: |
+            👎 Uh oh! The Netlify Preview failed to deploy for commit ${{ github.sha }}. Please check the Netlify logs for more information.
+        refresh-message-position: true
+        update-only: true
diff --git a/.husky/pre-push b/.husky/pre-push
@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+./scripts/check-branch.sh
diff --git a/Makefile b/Makefile
@@ -4,9 +4,17 @@ IMAGE:=spectrocloud/librarium
 # Retrieve all modified files in the content folder and compare the difference between the master branch git tree blob AND this commit's git tree blob
 CHANGED_FILE=$(shell git diff-tree -r --no-commit-id --name-only master HEAD | grep content)
 
+TEMP_DIR=$(shell $TMPDIR)
+
 help: ## Display this help
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[0m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
 
+
+initialize: ## Initialize the repository dependencies
+	@echo "initializing npm dependencies"
+	npm ci
+	npx husky-init
+
 clean: ## Clean build artifacts
 	rm -rf node_modules build public .cache .docusaurus
 	docker image rm $(IMAGE) || echo "No image exists."
@@ -27,6 +35,15 @@ build: ## Run npm build
 	rm -rf build
 	npm run build
 
+versions: ## Create Docusarus content versions
+	@echo "creating versions"
+	./scripts/versions.sh $(TMPDIR)
+
+
+versions-ci: ## Create Docusarus content versions in a GitHub Actions CI environment
+	@echo "creating versions"
+	./scripts/versions.sh $$RUNNER_TEMP
+
 ##@ Git Targets
 
 commit: ## Add a Git commit. Usage: make commit MESSAGE="<your message here>"
@@ -44,15 +61,22 @@ docker-start: docker-image ## Start a local development container
 	docker run --rm -it -v $(CURDIR)/docs:/librarium/docs/ -p 9000:9000 $(IMAGE)
 
 
+##@ Writing Checks
+
 sync-vale: ## Install Vale plugins
 	vale sync
 
 check-writing: ## Run Vale lint checks
 	vale $(CHANGED_FILE) 
 
+
+##@ Clean Server Artifacts
+
 fix-server: ## Fix server issues by removing the cache folder and reinstalling node modules
 	@echo "fixing server"
-	rm -rfv node_modules && rm -rfv .cache/ && npm ci
+	rm -rfv node_modules && npm ci && npm run clear
+
+###@ PDF Generation
 
 pdf: ## Generate PDF from docs
 	@echo "generating pdf"

diff --git a/README.md b/README.md
@@ -341,32 +341,46 @@ https://docusaurus.io/docs/markdown-features/code-blocks#highlighting-with-comme
 The copy button is shown by default in all code blocks. You can disable the copy button by passing in the parameter value `hideClipboard` in the markdown declaration of the code blocks. 
 
 Example 
-![Example](assets/docs/images/hide_copy_button_example.png)
+![Example](static/assets/docs/images/hide_copy_button_example.png)
 
 Result
 
-![Result](assets/docs/images/hide_copy_button.png)
+![Result](static/assets/docs/images/hide_copy_button.png)
 
 
-### Admonitions - Warning / Info Box
+### Admonitions - Warning / Info / Tip / Dange
 
 :::note
 
-Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. 
 
 :::
 
 
 :::caution
 
-Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`.
+
+:::
+
+
+:::tip
+
+Some **content** with _Markdown_ `syntax`. 
+
+:::
+
+
+:::danger
+
+Some **content** with _Markdown_ `syntax`.
 
 :::
 
 https://docusaurus.io/docs/markdown-features/admonitions
 
 
-The content must have a new line at the beginning and at the end of the tag like this:
+The content must have a new line at the beginning and at the end of the tag.
 
 ### Video
 
@@ -436,7 +450,7 @@ Approved words can be found in the [accept.txt](/vale/styles/Vocab/Internal/acce
 Rejected words automatically get flagged by Vale. To modify the list of rejected words, modify the [reject.txt](/vale/styles/Vocab/Internal/reject.txt) file.
 
 
-# Release
+## Release
 
 To create a new release, use the following steps:
 
@@ -445,8 +459,60 @@ To create a new release, use the following steps:
 3. Push up the commit and create a new pull request (PR).
 4. Merge PRs related to the upcoming release into the `release-X-X` branch.
 5. Merge the release branch.
+6. Create a new branch from the `master` branch. Use the following naming pattern `version-X-X`. This brach is used for versioning the documentation.
+7. Push the new version branch to the remote repository.
+8. Trigger a new build so that the new version is published.
 
 The semantic-release logic and the GitHub Actions in the [release.yaml](.github/workflows/release.yaml) will ensure the new release tag is created. 
 
 > **Warning**
 > Do not use `feat`,`perf` or `fix` or other semantic-release key words that trigger a version change. Use the commit message prefix `docs: yourMessageHere` for regular documentation commits.
+
+## Versioning
+
+> [!NOTE] 
+> Detailed documentation for versioning can be found in the internal [Versioning](https://spectrocloud.atlassian.net/wiki/spaces/DE/pages/1962639377/Versioning) guide.
+
+All versioned content belongs to a specific version branch. The version branch name follows the naming convention `version-X-X`. The version branch is used to generate versioned content.
+
+There are three files that are used for generating versioned content: 
+
+- [`versions.sh`](./scripts/versions.sh) - A bash script that loops through all the version branches and generates the versionioned content.
+
+- [`update_docusaurs_config.js`](./docsearch.config.json) - A node script that updates the `docusaurus.config.js` file with all the required vesioning parameters.
+
+- [`versionsOverride.json`](./versionsOverride.json) - A JSON file that contains the versioning overrides. These values are used to update the `docusaurus.config.js` file with non-default values.
+
+
+### Build Versioned Content Locally
+
+To build versioned content locally, use the following steps:
+
+1. Issue the following command to generate the versioned content.
+
+```shell
+make versions
+```
+
+2. Start a local development server to view the versioned content.
+
+```shell
+make start
+```
+
+
+3. Compile the versioned content to ensure a successful build.
+
+```shell
+make build
+```
+
+4. Remove the `versions.json` file and discard the changes to the `docusaurus.config.js` file.
+
+```shell
+rm versions.json
+```
+
+
+> [!WARNING] 
+> The `docuasurus.config.js` file is updated by the [`update_docusaurs_config.js`](./docusaurus.config.js) script. DO NOT commit this file with the updated changes.