Merge pull request #93 from ShippingBytes/chore/release-markdown-cli-doc

Add cli doc and doc folder to release bundle

Author: gianarb

.gitignore

@@ -4,3 +4,4 @@ dist/
 /datumctl
 # Nix stuff
 /result
+.generated/

.goreleaser.yaml

@@ -9,6 +9,8 @@ before:
   hooks:
     - go mod tidy
     - go generate ./...
+    - ./scripts/generate-cli-docs.sh
+    - ./scripts/package-docs.sh
 
 builds:
   - env:
@@ -57,7 +59,12 @@ changelog:
       - "^test:"
       - "^chore:"
 
-release: {}
+release:
+  extra_files:
+    - glob: .generated/datumctl-cli-docs.tar.gz
+      name_template: "{{ .ProjectName }}-cli-docs_{{ .Version }}.tar.gz"
+    - glob: .generated/datumctl-docs.tar.gz
+      name_template: "{{ .ProjectName }}-docs_{{ .Version }}.tar.gz"
 
 sboms:
   - artifacts: archive

docs/developer/README.md

@@ -8,3 +8,4 @@ development of the `datumctl` CLI.
 *   [Overview](./overview.md)
 *   [Authentication Flow](./authentication_flow.md)
 *   [Code Structure](./code_structure.md)
+*   [Releases](./releases.md)

docs/developer/releases.md

@@ -0,0 +1,45 @@
+# Releases
+
+This guide explains how to cut a `datumctl` release locally with GoReleaser and
+how the GitHub Actions workflow publishes the official artifacts.
+
+## Local workflow
+
+1. **Prepare the repo**
+   - Ensure `git status` is clean (GoReleaser refuses to run with dirty trees
+     unless you explicitly use `--snapshot`).
+   - Install the required tooling: supported Go version (see `go.mod`) and
+     [GoReleaser v2](https://goreleaser.com/install/).
+2. **Dry-run the release**
+   - Run `goreleaser release --snapshot --clean`.  
+     The `--snapshot` flag skips publishing and the `--clean` flag wipes `dist/`
+     before starting.
+   - The docs generation script (`scripts/generate-cli-docs.sh`) executes as part
+     of the `before` hooks, producing `.generated/datumctl-cli-docs.tar.gz`. That
+     tarball is registered as an extra release file, so the real release will
+     upload it automatically.
+3. **Tag and release**
+   - Create a semver tag (e.g. `git tag v0.10.0 && git push origin v0.10.0`).
+   - Run `goreleaser release --clean` if you need to publish from your machine.
+     Otherwise, let CI handle publishing after you push the tag.
+
+## CI/CD pipeline
+
+- The workflow at `.github/workflows/release.yaml` triggers on every pushed tag.
+- Steps executed on `ubuntu-latest`:
+  1. Checkout the repository with full history.
+  2. Install Syft (required for SBOMs) and set up the stable Go toolchain.
+  3. Run `goreleaser release --clean` via `goreleaser/goreleaser-action@v6`.
+- GoReleaser runs the same hooks as your local invocation, so the generated CLI
+  docs tarball, archives, packages, SBOMs, and checksums are all attached to the
+  GitHub release. The action uses `secrets/TAP_TOKEN` for `GITHUB_TOKEN`.
+
+## Tips and troubleshooting
+
+- If GoReleaser fails immediately with `dist is not empty`, remove the folder or
+  keep using `--clean`.
+- Network access is required for `go mod tidy` (first `before` hook); if you are
+  offline use `--skip=before` for local experimentation, but re-run the full flow
+  before tagging.
+- After the release completes you can inspect `.generated/cli-docs/` or
+  `.generated/datumctl-cli-docs.tar.gz` to verify the CLI documentation bundle.

flake.nix

@@ -66,6 +66,8 @@
             gotools
             go-task
             go-tools
+            goreleaser
+            syft
             git
           ];
 

go.sum

@@ -200,10 +200,6 @@ github.com/zalando/go-keyring v0.2.6 h1:r7Yc3+H+Ux0+M72zacZoItR3UDxeWfKTcabvkI8u
 github.com/zalando/go-keyring v0.2.6/go.mod h1:2TCrxYrbUNYfNS/Kgy/LSrkSQzZ5UPVH85RwfczwvcI=
 go.miloapis.com/activity v0.2.0 h1:/l5Ce713MSSlaPw3eS0aaVV+Btqo4TJ/evhD9SchPDQ=
 go.miloapis.com/activity v0.2.0/go.mod h1:sp04VDZnzqyj26+Cp10NkrA4YT3FXyN48wS8nw3zuRk=
-go.miloapis.com/milo v0.16.2 h1:MqrBQvTYWIWBlniJXqBe3ycO/sZxgkL2tYems4s1+LY=
-go.miloapis.com/milo v0.16.2/go.mod h1:xOFYvUsvSZV3z6eow5YdB5C/qRQf2s/5/arcfJs5XPg=
-go.miloapis.com/milo v0.17.1 h1:Qaulxmn+WZI4obYl9l0K4Ci4RYXoEGIzV787nonF490=
-go.miloapis.com/milo v0.17.1/go.mod h1:xOFYvUsvSZV3z6eow5YdB5C/qRQf2s/5/arcfJs5XPg=
 go.miloapis.com/milo v0.18.0 h1:+6HRLlRO2genWFnIw9803A1er9/vmRfP1EOC3ZlEF/U=
 go.miloapis.com/milo v0.18.0/go.mod h1:xOFYvUsvSZV3z6eow5YdB5C/qRQf2s/5/arcfJs5XPg=
 go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
@@ -278,8 +274,6 @@ k8s.io/metrics v0.35.0 h1:xVFoqtAGm2dMNJAcB5TFZJPCen0uEqqNt52wW7ABbX8=
 k8s.io/metrics v0.35.0/go.mod h1:g2Up4dcBygZi2kQSEQVDByFs+VUwepJMzzQLJJLpq4M=
 k8s.io/utils v0.0.0-20260108192941-914a6e750570 h1:JT4W8lsdrGENg9W+YwwdLJxklIuKWdRm+BC+xt33FOY=
 k8s.io/utils v0.0.0-20260108192941-914a6e750570/go.mod h1:xDxuJ0whA3d0I4mf/C4ppKHxXynQ+fxnkmQH0vTHnuk=
-sigs.k8s.io/controller-runtime v0.23.0 h1:Ubi7klJWiwEWqDY+odSVZiFA0aDSevOCXpa38yCSYu8=
-sigs.k8s.io/controller-runtime v0.23.0/go.mod h1:DBOIr9NsprUqCZ1ZhsuJ0wAnQSIxY/C6VjZbmLgw0j0=
 sigs.k8s.io/controller-runtime v0.23.1 h1:TjJSM80Nf43Mg21+RCy3J70aj/W6KyvDtOlpKf+PupE=
 sigs.k8s.io/controller-runtime v0.23.1/go.mod h1:B6COOxKptp+YaUT5q4l6LqUJTRpizbgf9KSRNdQGns0=
 sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 h1:IpInykpT6ceI+QxKBbEflcR5EXP7sU1kvOlxwZh5txg=
@@ -292,8 +286,6 @@ sigs.k8s.io/kustomize/kyaml v0.21.0 h1:7mQAf3dUwf0wBerWJd8rXhVcnkk5Tvn/q91cGkaP6
 sigs.k8s.io/kustomize/kyaml v0.21.0/go.mod h1:hmxADesM3yUN2vbA5z1/YTBnzLJ1dajdqpQonwBL1FQ=
 sigs.k8s.io/randfill v1.0.0 h1:JfjMILfT8A6RbawdsK2JXGBR5AQVfd+9TbzrlneTyrU=
 sigs.k8s.io/randfill v1.0.0/go.mod h1:XeLlZ/jmk4i1HRopwe7/aU3H5n1zNUcX6TM94b3QxOY=
-sigs.k8s.io/structured-merge-diff/v6 v6.3.1 h1:JrhdFMqOd/+3ByqlP2I45kTOZmTRLBUm5pvRjeheg7E=
-sigs.k8s.io/structured-merge-diff/v6 v6.3.1/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=
 sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482 h1:2WOzJpHUBVrrkDjU4KBT8n5LDcj824eX0I5UKcgeRUs=
 sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=
 sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=

scripts/generate-cli-docs.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+OUTPUT_DIR="${CLI_DOCS_OUTPUT_DIR:-$ROOT_DIR/.generated/cli-docs}"
+ARCHIVE_PATH="${CLI_DOCS_ARCHIVE_PATH:-$ROOT_DIR/.generated/datumctl-cli-docs.tar.gz}"
+
+rm -rf "${OUTPUT_DIR}"
+mkdir -p "${OUTPUT_DIR}"
+
+pushd "${ROOT_DIR}" >/dev/null
+go run main.go docs generate-cli-docs --output-dir "${OUTPUT_DIR}"
+popd >/dev/null
+
+mkdir -p "$(dirname "${ARCHIVE_PATH}")"
+tar -C "${OUTPUT_DIR}" -czf "${ARCHIVE_PATH}" .

scripts/package-docs.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DOCS_DIR="${DOCS_SOURCE_DIR:-$ROOT_DIR/docs}"
+ARCHIVE_PATH="${DOCS_ARCHIVE_PATH:-$ROOT_DIR/.generated/datumctl-docs.tar.gz}"
+
+if [ ! -d "${DOCS_DIR}" ]; then
+  echo "Docs directory not found: ${DOCS_DIR}" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "${ARCHIVE_PATH}")"
+rm -f "${ARCHIVE_PATH}"
+tar -C "${DOCS_DIR}" -czf "${ARCHIVE_PATH}" .