docs: write documentation for upcoming v0.8.0 release (#139)

purpleclay · Jun 10, 2024 · ae6dde1 · ae6dde1
1 parent cd458ab
commit ae6dde1
Show file tree

Hide file tree

Showing 25 changed files with 368 additions and 103 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -29,14 +29,14 @@ jobs:
     uses: purpleclay/github/.github/workflows/go-test.yml@main
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-24.04, macos-14, windows-2022]
     with:
       go-version: ${{ vars.GO_VERSION }}
     secrets:
       github-token: ${{ secrets.GITHUB_TOKEN }}
 
   lint:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -13,7 +13,7 @@ on:
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     permissions:
       actions: read
       contents: read

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -19,7 +19,7 @@ permissions:
 
 jobs:
   build-docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -31,7 +31,7 @@ jobs:
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          password: ${{ secrets.GH_GHCR }}
 
       - run: docker pull ghcr.io/purpleclay/mkdocs-material-insiders:${{ vars.MKDOCS_MATERIAL_INSIDERS_VERSION }}
 

diff --git a/.github/workflows/nsv.yml b/.github/workflows/nsv.yml
@@ -4,7 +4,7 @@ on:
 
 jobs:
   nsv:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     permissions:
       contents: write
     steps:

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -12,7 +12,7 @@ permissions:
 
 jobs:
   goreleaser:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Git Clone
         uses: actions/checkout@v4
@@ -48,13 +48,6 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: GitLab Login
-        uses: docker/login-action@v3
-        with:
-          registry: registry.gitlab.com
-          username: ${{ secrets.GL_DOCKER_USERNAME }}
-          password: ${{ secrets.GL_DOCKER_PASSWORD }}
-
       - name: GoReleaser
         uses: goreleaser/goreleaser-action@v5
         with:

diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml
@@ -16,7 +16,7 @@ permissions:
 
 jobs:
   shellcheck:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     name: shellcheck
     steps:
       - name: Checkout repository

diff --git a/.goreleaser.yaml b/.goreleaser.yaml
@@ -35,7 +35,6 @@ archives:
       {{- if .Arm }}v{{ .Arm }}{{ end }}
     builds:
       - nsv
-    rlcp: true
     format_overrides:
       - goos: windows
         format: zip
@@ -58,7 +57,7 @@ changelog:
       - "^ci"
   groups:
     - title: "Dependency Updates"
-      regexp: "^.*feat\\(deps\\)*:+.*$"
+      regexp: "^.*fix\\(deps\\)*:+.*$"
       order: 30
     - title: "New Features"
       regexp: "^.*feat[(\\w)]*:+.*$"
@@ -100,7 +99,6 @@ dockers:
   - image_templates:
       - "purpleclay/nsv:{{ .Tag }}-amd64"
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-amd64"
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-amd64"
     dockerfile: Dockerfile
     use: buildx
     build_flag_templates:
@@ -117,7 +115,6 @@ dockers:
   - image_templates:
       - "purpleclay/nsv:{{ .Tag }}-arm64"
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-arm64"
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-arm64"
     dockerfile: Dockerfile
     use: buildx
     build_flag_templates:
@@ -142,10 +139,6 @@ docker_manifests:
     image_templates:
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-amd64"
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-arm64"
-  - name_template: "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}"
-    image_templates:
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-amd64"
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-arm64"
   - name_template: "purpleclay/nsv:latest"
     image_templates:
       - "purpleclay/nsv:{{ .Tag }}-amd64"
@@ -154,10 +147,6 @@ docker_manifests:
     image_templates:
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-amd64"
       - "ghcr.io/purpleclay/nsv:{{ .Tag }}-arm64"
-  - name_template: "registry.gitlab.com/purpleclay/nsv:latest"
-    image_templates:
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-amd64"
-      - "registry.gitlab.com/purpleclay/nsv:{{ .Tag }}-arm64"
 
 brews:
   - name: nsv

diff --git a/README.md b/README.md
@@ -17,11 +17,13 @@ The power is at your fingertips.
 ### Features
 
 - First-class support for semantic versioning. Conventional commits help give it a nudge in the right direction.
+- Configure your Conventional Commit prefixes for complete control.
 - If you batch your commits per release or prefer a continuous delivery approach, it has you covered.
 - Context-aware, it automatically switches to a monorepo workflow.
 - Extend the power of your commits through commands to dynamically change your semantic release workflow.
 - Explore how to use it within the purpose-built playground.
 - Get up and running in seconds within GitHub and GitLab with the available [action](https://github.com/purpleclay/nsv-action) or [template](https://gitlab.com/purpleclay/nsv).
+- First class [Dagger](https://dagger.io/) support.
 
 ## Documentation
 

diff --git a/Taskfile.yaml b/Taskfile.yaml
@@ -70,3 +70,10 @@ tasks:
       TEST_OPTIONS: '{{default "-bench=. -benchtime 5s -benchmem" .TEST_OPTIONS}}'
     cmds:
       - go test {{.TEST_OPTIONS}} -run=^# ./...
+
+  docs:
+    desc: Builds and hosts the MkDocs documentation
+    vars:
+      MKDOCS_MATERIAL_VERSION: '{{default "9.5.26-insiders-4.53.11" .MKDOCS_MATERIAL_VERSION}}'
+    cmds:
+      - docker run --rm -it -p 8000:8000 -v $PWD:/docs ghcr.io/purpleclay/mkdocs-material-insiders:{{.MKDOCS_MATERIAL_VERSION}}
diff --git a/docs/ci/dagger.md b/docs/ci/dagger.md
@@ -0,0 +1,84 @@
+---
+icon: material/sword
+social:
+  cards: false
+status: new
+---
+
+# Using Dagger in your CI
+
+<span class="rounded-pill">:material-test-tube: experimental</span>
+
+## GitHub Action
+
+Run [nsv](https://daggerverse.dev/mod/github.com/purpleclay/daggerverse/nsv) using the official Dagger [GitHub Action](https://github.com/dagger/dagger-for-github). The Dagger Cloud offers enhanced layer caching, which can be enabled by setting a `DAGGER_CLOUD_TOKEN` environment variable.
+
+```{.yaml .no-select linenums="1"}
+name: ci
+on:
+  push:
+    branches:
+      - main
+jobs:
+  nsv:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GH_NSV }} # (1)!
+
+      - name: Tag
+        uses: dagger/dagger-for-github@v5
+        env:
+          GPG_PRIVATE_KEY: "${{ secrets.GPG_PRIVATE_KEY }}"
+          GPG_PASSPHRASE: "${{ secrets.GPG_PASSPHRASE }}"
+        with:
+          verb: call
+          module: github.com/purpleclay/daggerverse/nsv
+          args: --src . tag --show --gpg-private-key env:GPG_PRIVATE_KEY --gpg-passphrase env:GPG_PASSPHRASE
+          cloud-token: ${{ secrets.DAGGER_CLOUD_TOKEN }}
+```
+
+1. A PAT token triggers another workflow after tagging the repository; this is optional.
+
+## GitLab Template
+
+The same Dagger experience is possible within GitLab using the Purple Clay [template](https://gitlab.com/purpleclay/templates/-/blob/main/dagger/README.md?ref_type=heads). The Dagger Cloud offers enhanced layer caching, which can be enabled by setting a `DAGGER_CLOUD_TOKEN` environment variable.
+
+```{.yaml .no-select linenums="1" hl_lines="28-29"}
+include:
+  - "https://gitlab.com/purpleclay/templates/-/raw/dagger/0.11.6/dagger/Mixed.gitlab-ci.yml"
+
+  nsv:
+    extends: [.dagger]
+    stage: release
+    rules:
+      - if: $CI_COMMIT_TAG
+        when: never
+      - if: $CI_PIPELINE_SOURCE == "schedule"
+        when: never
+      - if: $CI_MERGE_REQUEST_IID
+        when: never
+      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+        when: on_success
+    variables:
+      GIT_DEPTH: 0
+      GIT_STRATEGY: clone
+      DAGGER_MODULE: "github.com/purpleclay/daggerverse/nsv"
+      DAGGER_ARGS: >-
+        --src .
+        tag
+        --show
+        --paths ${WORKING_DIRECTORY}
+        --gpg-private-key env:NSV_GPG_PRIVATE_KEY
+        --gpg-passphrase env:NSV_GPG_PASSPHRASE
+    before_script: # (1)!
+      - PROJECT_URL=${CI_PROJECT_URL#"https://"}
+      - git remote set-url origin "https://oauth2:${NSV_GITLAB_TOKEN}@${PROJECT_URL}.git"
+```
+
+1. To push a newly created tag, an access token with `:write_repository` permissions is required. Here, it is assigned to the `NSV_GITLAB_TOKEN` CI variable.
diff --git a/docs/github-action.md → docs/ci/github-action.md b/docs/github-action.md → docs/ci/github-action.md
@@ -12,7 +12,7 @@ To get up and running within a GitHub workflow, include the publicly available `
 
 If you wish to tag the repository without triggering another workflow, you must set the permissions of the job to `contents: write`.
 
-```{.yaml linenums="1" hl_lines="10"}
+```{.yaml .no-select linenums="1" hl_lines="10"}
 name: ci
 on:
   push:

diff --git a/docs/gitlab-template.md → docs/ci/gitlab-template.md b/docs/gitlab-template.md → docs/ci/gitlab-template.md
@@ -10,7 +10,7 @@ To get up and running within a GitLab pipeline, include the publicly available `
 
 ## Tagging a repository
 
-```{.yaml linenums="1"}
+```{.yaml .no-select linenums="1"}
 include:
   - https://gitlab.com/purpleclay/nsv/-/raw/main/nsv.gitlab-ci.yml
 ```
diff --git a/docs/commands.md b/docs/commands.md
@@ -1,7 +1,6 @@
 ---
 icon: material/apple-keyboard-command
 description: Advanced control of semantic versioning through dedicated commands
-status: new
 ---
 
 # Control your workflow with Commands

diff --git a/docs/configurable-prefixes.md b/docs/configurable-prefixes.md
@@ -0,0 +1,46 @@
+---
+icon: material/apple-keyboard-command
+description: Advanced control of semantic versioning through dedicated commands
+status: new
+---
+
+# Configure your Conventional prefixes
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) offers a fantastic approach to controlling semantic versioning through commit prefixes. An industry standard convention devised by the Angular team is most commonly used to date.
+
+- `BREAKING CHANGE`: any commit with this footer triggers a major update.
+- `!`: any conventional prefix with this suffix (e.g. `refactor!`) triggers a major update.
+- `feat`: triggers a minor update.
+- `fix`: triggers a patch update.
+
+## Defining your own rules
+
+- `breaking`: triggers a major update `1.0.0` ~> `2.0.0`.
+- `feat`, `deps`: triggers a minor update `0.1.0` ~> `0.2.0`.
+- `fix`, `docs`, `styles`: triggers a patch update `0.3.1` ~> `0.3.2`.
+
+=== "ENV"
+
+    ```{ .sh .no-select }
+    NSV_MAJOR_PREFIXES=breaking \
+      NSV_MINOR_PREFIXES=feat,deps \
+      NSV_PATCH_PREFIXES=fix,docs,styles \
+      nsv next
+    ```
+
+=== "CLI"
+
+    ```{ .sh .no-select }
+    nsv next --major-prefixes breaking \
+      --minor-prefixes feat,deps \
+      --patch-prefixes fix,docs,styles
+    ```
+
+Don't worry—when defining your custom prefixes, both the `BREAKING CHANGE` footer and the `!` suffix are automatically supported.
+
+## How prefix matching works
+
+`nsv` matches a prefix in one of two ways:
+
+- `breaking` is a <u>wildcard</u> prefix capable of matching against an optional scope.
+- `breaking(api)` is an <u>exact</u> match only.