docs: extend documentation to include new patch sub-command (#169)

purpleclay · Sep 10, 2024 · fa6b0db · fa6b0db
1 parent 2bf7bb0
commit fa6b0db
Show file tree

Hide file tree

Showing 11 changed files with 217 additions and 22 deletions.
diff --git a/cmd/patch.go b/cmd/patch.go
@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"bytes"
+	"errors"
 	"text/template"
 
 	"github.com/purpleclay/chomp"
@@ -13,8 +14,9 @@ import (
 )
 
 var (
-	commitMessageTmpl = "chore: patched files for release {{.Tag}}"
-	commitTmpl        *template.Template
+	commitMessageTmpl   = "chore: patched files for release {{.Tag}}"
+	commitTmpl          *template.Template
+	errRequiredHookFlag = errors.New("a hook must be provided when patching files")
 
 	patchLongDesc = `Patch files in a repository with the next semantic version based on the conventional commit
 history of your repository.
@@ -61,6 +63,11 @@ func patchCmd(opts *Options) *cobra.Command {
 		Short: "Patch files within a repository with the next semantic version",
 		Long:  patchLongDesc,
 		PreRunE: func(_ *cobra.Command, args []string) error {
+			// This will be removed once auto-patching of common files is in place
+			if opts.Hook == "" {
+				return errRequiredHookFlag
+			}
+
 			opts.Paths = defaultIfEmpty(args, []string{git.RelativeAtRoot})
 
 			if err := verifyTextTemplate(opts.CommitMessage); err != nil {

diff --git a/docs/docker/dagger.md b/docs/docker/dagger.md
@@ -2,6 +2,7 @@
 icon: material/sword
 social:
   cards: false
+status: new
 ---
 
 # Running with Dagger
@@ -78,3 +79,12 @@ Tags a repository with the next semantic version. For full configuration [option
 ```{ .sh .no-select }
 dagger call -m github.com/purpleclay/daggerverse/nsv --src . tag
 ```
+
+## Patching files with the next version
+
+Patch files within a repository using the next semantic version. For full configuration [options](../patch-files.md).
+
+```{ .sh .no-select }
+dagger call -m github.com/purpleclay/daggerverse/nsv --src . patch \
+  --hook "./scripts/patch.sh"
+```
diff --git a/docs/git-signing.md b/docs/git-signing.md
@@ -0,0 +1,23 @@
+---
+icon: material/file-sign
+description: Adhere to best practice with commit or tag gpg signing
+social:
+  cards: false
+---
+
+# Git GPG signing
+
+If you require GPG signing, please ensure your git config is correct before running `nsv`.
+
+## Importing a GPG key
+
+[gpg-import](https://github.com/purpleclay/gpg-import) is a tool you can easily integrate into your CI workflow and only needs a single environment variable (`GPG_PRIVATE_KEY`) to import a GPG key and configure your git config.
+
+## Committer impersonation
+
+When tagging your repository, `nsv` will identify the person associated with the commit that triggered the release and dynamically passes these to `git` through the `user.name` and `user.email` config settings.
+
+Any of the following conditions will remove the need for impersonation:
+
+1. The repository has the `user.name` and `user.email` settings already defined in git config.
+1. The git environment variables `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` exist.
diff --git a/docs/hooks.md b/docs/hooks.md
@@ -1,7 +1,6 @@
 ---
 icon: material/hook
-description: Extend your release workflow by patching files with the next semantic version
-status: new
+description: Extend your release workflow by executing a custom hook
 ---
 
 # Executing a custom hook

diff --git a/docs/patch-files.md b/docs/patch-files.md
@@ -0,0 +1,60 @@
+---
+icon: material/file-edit-outline
+description: Automatically patch files in your repository with the next semantic version
+status: new
+---
+
+# Patch files with the next semantic version
+
+<span class="rounded-pill">:material-test-tube: experimental</span>
+
+Let `nsv` patch files in your repository with the next calculated semantic version by executing a custom hook:
+
+=== "ENV"
+
+    ```{ .sh .no-select }
+    NSV_HOOK="./scripts/patch.sh" nsv patch
+    ```
+
+=== "CLI"
+
+    ```{ .sh .no-select }
+    nsv patch --hook "./scripts/patch.sh"
+    ```
+
+Any file changes are committed with the default message `chore: patched files for release <version>`.
+
+!!! tip "Auto-patching is on the horizon."
+
+    Soon, `nsv` will recognize standard project files and automatically patch them
+    with the next semantic version. How cool is that! :material-sunglasses:
+
+## Signing your commit
+
+If you require GPG signing, you can configure it [here](./git-signing.md).
+
+## Using a custom commit message
+
+You can change the commit message. Support for Go templating provides extra [customization](./reference/templating.md#commit-message).
+
+=== "ENV"
+
+    ```{ .sh .no-select }
+    NSV_COMMIT_MESSAGE="chore: bumped files to {{.Tag}}" nsv patch
+    ```
+
+=== "CLI"
+
+    ```{ .sh .no-select }
+    nsv patch --commit-message "chore: bumped files to {{.Tag}}"
+    ```
+
+Resulting in a commit message of:
+
+```{ .text .no-select .no-copy }
+chore: bumped files to 0.2.0
+```
+
+## Version template customization
+
+Internally, `nsv` utilizes a go template to construct the next semantic version. Runtime customization of this template is available [here](./next-version.md#version-template-customization).
diff --git a/docs/reference/cli/nsv-patch.md b/docs/reference/cli/nsv-patch.md
@@ -0,0 +1,99 @@
+---
+icon: material/console
+social:
+  cards: false
+status: new
+---
+
+# nsv patch
+
+```{ .text .no-select .no-copy }
+Patch files in a repository with the next semantic version based on the
+conventional commit history of your repository.
+
+Environment Variables:
+
+| Name               | Description                                            |
+|--------------------|--------------------------------------------------------|
+| LOG_LEVEL          | the level of logging when printing to stderr           |
+|                    | (default: info)                                        |
+| NO_COLOR           | switch to using an ASCII color profile within the      |
+|                    | terminal                                               |
+| NO_LOG             | disable all log output                                 |
+| NSV_COMMIT_MESSAGE | a custom message when committing file changes,         |
+|                    | supports go text templates. The default is: "chore:    |
+|                    | patched files for release {{.Tag}}"                    |
+| NSV_DRY_RUN        | no changes will be made to the repository              |
+| NSV_FORMAT         | provide a go template for changing the default version |
+|                    | format                                                 |
+| NSV_HOOK           | a user-defined hook that will be executed before any   |
+|                    | file changes are committed with the next semantic      |
+|                    | version                                                |
+| NSV_MAJOR_PREFIXES | a comma separated list of conventional commit prefixes |
+|                    | or triggering a major semantic version increment       |
+| NSV_MINOR_PREFIXES | a comma separated list of conventional commit prefixes |
+|                    | for triggering a minor semantic version increment      |
+| NSV_PATCH_PREFIXES | a comma separated list of conventional commit prefixes |
+|                    | for triggering a patch semantic version increment      |
+| NSV_PRETTY         | pretty-print the output of the next semantic version   |
+|                    | in a given format. The format can be one of either     |
+|                    | full or compact. Must be used in conjunction with      |
+|                    | NSV_SHOW (default: full)                               |
+| NSV_SHOW           | show how the next semantic version was generated       |
+
+Hook Environment Variables:
+
+| Name                  | Description                                         |
+|-----------------------|-----------------------------------------------------|
+| NSV_NEXT_TAG          | the next calculated semantic version                |
+| NSV_PREV_TAG          | the last semantic version as identified within the  |
+|                       | tag                                                 |
+|                       | history of the current repository                   |
+| NSV_WORKING_DIRECTORY | the working directory (or path) relative to the     |
+|                       | root of the current repository. It will be empty if |
+|                       | not a monorepo                                      |
+```
+
+## Usage
+
+```{ .text .no-select .no-copy }
+nsv patch [<path>...] [flags]
+```
+
+## Flags
+
+```{ .text .no-select .no-copy }
+-M, --commit-message string    a custom message when committing file changes,
+                               supports go text templates (default "chore:
+                               patched files for release {{.Tag}}")
+    --dry-run                  no changes will be made to the repository
+-f, --format string            provide a go template for changing the default
+                               version format
+-h, --help                     help for tag
+    --hook string              a user-defined hook that will be executed before
+                               any file changes are committed with the next
+                               semantic version
+    --major-prefixes strings   a comma separated list of conventional commit
+                               prefixes for triggering a major semantic version
+                               increment
+    --minor-prefixes strings   a comma separated list of conventional commit
+                               prefixes for triggering a minor semantic version
+                               increment
+    --patch-prefixes strings   a comma separated list of conventional commit
+                               prefixes for triggering a patch semantic version
+                               increment
+-p, --pretty string            pretty-print the output of the next semantic
+                               version in a given format. The format can be one
+                               of either full or compact. Must be used in
+                               conjunction with --show (default "full")
+-s, --show                     show how the next semantic version was generated
+```
+
+## Global Flags
+
+```{ .text .no-select .no-copy }
+--log-level string   the level of logging when printing to stderr
+                     (default "info")
+--no-color           switch to using an ASCII color profile within the terminal
+--no-log             disable all log output
+```
diff --git a/docs/reference/cli/nsv-tag.md b/docs/reference/cli/nsv-tag.md
@@ -1,6 +1,5 @@
 ---
 icon: material/console
-status: new
 social:
   cards: false
 ---
@@ -20,8 +19,15 @@ Environment Variables:
 | NO_COLOR           | switch to using an ASCII color profile within the      |
 |                    | terminal                                               |
 | NO_LOG             | disable all log output                                 |
+| NSV_COMMIT_MESSAGE | a custom message when committing file changes,         |
+|                    | supports go text templates. The default is: "chore:    |
+|                    | patched files for release {{.Tag}}                     |
+|                    | {{.SkipPipelineTag}}"                                  |
+| NSV_DRY_RUN        | no changes will be made to the repository              |
 | NSV_FORMAT         | provide a go template for changing the default version |
 |                    | format                                                 |
+| NSV_HOOK           | a user-defined hook that will be executed before the   |
+|                    | repository is tagged with the next semantic version    |
 | NSV_MAJOR_PREFIXES | a comma separated list of conventional commit prefixes |
 |                    | or triggering a major semantic version increment       |
 | NSV_MINOR_PREFIXES | a comma separated list of conventional commit prefixes |

diff --git a/docs/reference/env-vars.md b/docs/reference/env-vars.md
@@ -1,6 +1,5 @@
 ---
 icon: material/earth
-status: new
 title: Dynamic Configuration
 description: Customize behavior with environment variables
 ---

diff --git a/docs/reference/templating.md b/docs/reference/templating.md
@@ -2,7 +2,6 @@
 icon: material/application-cog-outline
 title: Flexibility through Templating
 description: Customize behavior with go templates
-status: new
 ---
 
 # Customization with Templates

diff --git a/docs/tag-version.md b/docs/tag-version.md
@@ -1,7 +1,6 @@
 ---
 icon: material/tag-check-outline
 description: Automatically tag your repository with the next semantic version
-status: new
 ---
 
 # Tag the Next Semantic Version
@@ -78,24 +77,15 @@ Resulting in a tag message of:
 chore: tagged release 0.2.0 from 0.1.0
 ```
 
-## Signing your tag
+## Signing your commit or tag
 
-If you require your tag to be signed, please ensure your git config is correct before running `nsv`. [gpg-import](https://github.com/purpleclay/gpg-import) is a tool you can easily integrate into your CI workflow and only needs a single environment variable.
+If you require GPG signing, you can configure it [here](./git-signing.md).
 
 ## Version template customization
 
 Internally `nsv` utilizes a go template when constructing the next semantic version. Runtime customization of this template is available [here](./next-version.md#version-template-customization).
 
-## Committer impersonation
-
-When tagging your repository, `nsv` will identify the person associated with the commit that triggered the release and dynamically passes these to `git` through the `user.name` and `user.email` config settings.
-
-Any of the following conditions will remove the need for impersonation:
-
-1. The repository has the `user.name` and `user.email` settings already defined in git config.
-1. The git environment variables `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` exist.
-
-## Executing a custom hook :material-new-box:{.new-feature title="Feature added on the 2nd of September 2024"}
+## Executing a custom hook
 
 Before tagging your repository, `nsv` can execute a custom [hook](./hooks.md). If changes are detected, it will commit them, and then this new commit is tagged.
 
@@ -111,7 +101,7 @@ Before tagging your repository, `nsv` can execute a custom [hook](./hooks.md). I
     nsv tag --hook "./scripts/patch.sh"
     ```
 
-It uses the default commit message of `chore: tagged release <version> [skip ci]`.
+It uses the default commit message of `chore: patched files for release <version> [skip ci]`.
 
 ### Using a custom commit message
 
@@ -135,7 +125,7 @@ Resulting in a commit message of:
 chore: bumped to 0.2.0 [skip ci]
 ```
 
-## Skip changes during a dry run :material-new-box:{.new-feature title="Feature added on the 2nd of September 2024"}
+## Skip changes during a dry run
 
 Run `nsv` within dry-run mode to skip tagging your repository and revert any changes a hook makes. This is perfect for testing.
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -48,6 +48,8 @@ nav:
       # - Playground: playground.md
       - Tag Version: tag-version.md
       - Hooks: hooks.md
+      - Patch Files: patch-files.md
+      - Git Signing: git-signing.md
       - Monorepos: monorepos.md
       - Pretty Print: pretty.md
       - Installation:
@@ -67,6 +69,7 @@ nav:
       - Version Templating: reference/templating.md
       - CLI:
           - nsv: reference/cli/nsv.md
+          - nsv patch: reference/cli/nsv-patch.md
           - nsv next: reference/cli/nsv-next.md
           # - nsv playground: reference/cli/nsv-playground.md
           - nsv tag: reference/cli/nsv-tag.md