feat: add release standardization templates and ADR-0015 (#160)

HerbHall · claude · web-flow · commit b6985cd027ad · 2026-03-02T09:41:09.000-05:00
Templates for standardizing versioning and changelog management across
all DevSpace projects using release-please + git-cliff + VERSION file.

- release-please-config.json: default simple release type with changelog sections
- release-please-manifest.json: starter manifest for new projects
- release-please.yml: GitHub Actions workflow template
- cliff.toml: git-cliff config for Phase 2 changelog enhancement
- ADR-0015: documents decision and rollout plan

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- **Release standardization templates** (ADR-0015): release-please config, manifest, workflow, and git-cliff templates in `project-templates/`
+- **ADR-0015**: Documents the decision to standardize on release-please + git-cliff + VERSION file across all projects
+
 ## v2.3.0 -- 2026-03-01
 
 Rules reconciliation, drift detection, and project settings enforcement.
diff --git a/README.md b/README.md
@@ -44,6 +44,10 @@ Setup creates symlinks from `~/.claude/` to the DevKit clone (or copies files in
 | `claude/settings.template.json` | User-level Claude Code settings — broad permissions, hooks, plugins |
 | `project-templates/settings.json` | Project-level Claude Code permissions — commit to repo for collaborators |
 | `project-templates/workspace-claude-md-template.md` | Workspace CLAUDE.md template — fill in your projects |
+| `project-templates/release-please-config.json` | release-please config — set `release-type` per stack (see ADR-0015) |
+| `project-templates/release-please-manifest.json` | release-please manifest — set current version on first setup |
+| `project-templates/release-please.yml` | GitHub Actions workflow — copy to `.github/workflows/` |
+| `project-templates/cliff.toml` | git-cliff changelog template — Phase 2 enhancement |
 | `mcp/memory-seeds.md` | MCP Memory bootstrap — replace with your profile |
 | `mcp/claude-desktop.template.json` | MCP server config — fill in tokens and paths |
 
diff --git a/docs/ADR-0015-release-standardization.md b/docs/ADR-0015-release-standardization.md
@@ -0,0 +1,160 @@
+# ADR-0015: Release Standardization
+
+## Status
+
+Accepted
+
+## Date
+
+2026-03-02
+
+## Context
+
+10 projects under DevSpace have fragmented version tracking and inconsistent
+changelog practices:
+
+- **Version source of truth** varies: `VERSION` file (3 projects), `Cargo.toml`
+  (1), Dockerfile ARG (1), git tags only (1), nothing (4).
+- **Changelog practices** are inconsistent: manual Keep a Changelog (3), GoReleaser
+  auto-generated (1), none (6).
+- **Release automation** exists for 3 projects (SubNetree, Runbooks, DigitalRain)
+  but each uses a different pattern. The other 7 have no release infrastructure.
+- **Version drift** between files is a known risk (KG#82) -- Runbooks had version
+  in Dockerfile ARG but not in package.json.
+
+All projects already use conventional commits, which is the prerequisite for
+automated versioning.
+
+## Decision
+
+Standardize all projects on three components:
+
+### 1. VERSION File as Single Source of Truth
+
+Every project has a plain-text `VERSION` file at the repo root containing
+`X.Y.Z`. Stack-native files (package.json, Cargo.toml, Dockerfile ARG) are
+synced from it by the release tool.
+
+### 2. release-please for Automated Release Management
+
+[release-please](https://github.com/googleapis/release-please) (Google, v4
+GitHub Action) creates and maintains a Release PR on every push to main:
+
+- Analyzes conventional commits to determine the next semver version
+- Updates `VERSION`, `CHANGELOG.md`, and stack-native files in a PR
+- Human merges the Release PR (one-click review gate)
+- Creates a git tag and GitHub Release on merge
+- The tag triggers existing `release.yml` workflows (GoReleaser, Docker, cargo)
+
+release-please is chosen over semantic-release because:
+
+- Works with standard `GITHUB_TOKEN` (no branch protection workaround needed)
+- The Release PR provides a human review gate (aligns with core principle #3)
+- Native support for Go, Rust, and Node.js release types
+- Existing tag-triggered release.yml workflows are unchanged
+- No Node.js dependency in CI (runs as a GitHub Action)
+
+### 3. git-cliff for Changelog Generation (Phase 2)
+
+[git-cliff](https://github.com/orhun/git-cliff) generates high-quality
+changelogs from conventional commits using Tera templates. It replaces
+release-please's built-in changelog with customizable output.
+
+git-cliff is deferred to Phase 2 to avoid debugging two new tools simultaneously.
+Initial rollout uses release-please's built-in changelog.
+
+### Release-Type Mapping
+
+| Stack | release-type | Files Managed |
+|-------|-------------|---------------|
+| Go | `go` | VERSION, CHANGELOG.md |
+| Rust | `rust` | VERSION, Cargo.toml, CHANGELOG.md |
+| Node.js / React | `node` | VERSION, package.json, CHANGELOG.md |
+| Docker extensions | `node` + extra-files | VERSION, package.json, Dockerfile, CHANGELOG.md |
+| C# / .NET | `simple` + extra-files | VERSION, .csproj, CHANGELOG.md |
+| PowerShell / generic | `simple` | VERSION, CHANGELOG.md |
+
+### Release Flow
+
+```text
+Feature PRs merge to main (conventional commits)
+  -> release-please detects new commits
+  -> Creates/updates Release PR ("chore(main): release X.Y.Z")
+  -> Human merges Release PR
+  -> release-please creates git tag (vX.Y.Z) + GitHub Release
+  -> Tag triggers existing release.yml (GoReleaser, Docker, cargo)
+```
+
+### Per-Project Configuration
+
+Each project gets three files:
+
+- `release-please-config.json` -- release type, version file path, changelog sections
+- `.release-please-manifest.json` -- current version (set manually on first setup)
+- `.github/workflows/release-please.yml` -- GitHub Actions workflow
+
+Templates for all three are in `project-templates/`.
+
+## Alternatives Considered
+
+### semantic-release
+
+Fully headless automation (every qualifying push to main triggers a release).
+Rejected because:
+
+- Cannot push version/changelog commits back to protected branches without a
+  GitHub App token -- operational burden with our enforced branch protection
+- No human review gate before releases
+- Requires Node.js in CI even for Go/Rust/C# projects
+- Monorepo support is effectively abandoned
+
+### Manual Tagging (status quo)
+
+Human decides when to release, manually creates tags and GitHub Releases.
+Rejected because:
+
+- Inconsistent across projects (some have it, most don't)
+- VERSION files drift from tags
+- No automated changelog generation
+- Releases are skipped because the manual process is tedious
+
+### git-cliff Standalone
+
+Changelog generator only -- no version management or release automation.
+Not rejected, but insufficient alone. Adopted as a Phase 2 complement to
+release-please for higher-quality changelog output.
+
+## Consequences
+
+### Positive
+
+- Every project has a consistent release process
+- VERSION file is the single source of truth -- no more drift
+- Changelogs are auto-generated from conventional commits
+- Release PRs provide a review checkpoint before publishing
+- Existing release.yml workflows (GoReleaser, Docker, cargo) are unchanged
+- New projects get release infrastructure from day 1 via devkit templates
+
+### Negative
+
+- release-please adds a "chore: release" commit to main on every release
+- C#/.NET support requires workarounds (not a first-class release type)
+- The Release PR must be manually merged (intentional, but adds a step)
+- git-cliff integration (Phase 2) requires coordinating two tools
+
+### Risks
+
+- release-please is maintained by Google but could be deprecated
+- `extra-files` marker syntax (`x-release-please-version`) is mildly invasive
+- Projects with irregular commit history may generate noisy first changelogs
+  (mitigated with `bootstrap-sha` to exclude ancient history)
+
+## Rollout Plan
+
+1. **Phase 1**: DevKit templates and this ADR
+2. **Phase 2**: Projects with existing releases (SubNetree, Runbooks, DigitalRain)
+3. **Phase 3**: Projects with some infrastructure (DevKit, Samverk, RunNotes, DockPulse)
+4. **Phase 4**: Greenfield projects (CLI-Play, IPScan, PacketDeck)
+5. **Phase 5** (future): git-cliff integration for enhanced changelogs
+
+Each phase is independent. Phases 2-4 can run in parallel once templates are ready.
diff --git a/project-templates/cliff.toml b/project-templates/cliff.toml
@@ -0,0 +1,60 @@
+[changelog]
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+"""
+body = """
+{%- macro remote_url() -%}
+  https://github.com/HerbHall/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
+
+{% if version -%}
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else -%}
+## [Unreleased]
+{% endif -%}
+
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group | striptags | trim | upper_first }}
+{% for commit in commits -%}
+- {% if commit.scope %}*({{ commit.scope }})* {% endif -%}
+{% if commit.breaking %}[**breaking**] {% endif -%}
+{{ commit.message | upper_first }}
+{% endfor %}
+{% endfor -%}
+"""
+footer = ""
+trim = true
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+split_commits = false
+commit_parsers = [
+  { message = "^feat", group = "Features" },
+  { message = "^fix", group = "Bug Fixes" },
+  { message = "^perf", group = "Performance" },
+  { message = "^refactor", group = "Refactoring" },
+  { message = "^doc", group = "Documentation" },
+  { message = "^test", group = "Testing" },
+  { message = "^style", group = "Styling" },
+  { message = "^chore", group = "Miscellaneous" },
+  { message = "^ci", group = "CI/CD" },
+  { message = "^revert", group = "Reverts" },
+]
+filter_commits = true
+tag_pattern = "v[0-9].*"
+ignore_tags = ""
+topo_order = false
+sort_commits = "newest"
+
+[bump]
+features_always_bump_minor = true
+breaking_always_bump_major = true
+initial_tag = "0.1.0"
+
+[remote.github]
+owner = "HerbHall"
+repo = "REPO_NAME"
diff --git a/project-templates/release-please-config.json b/project-templates/release-please-config.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "version-file": "VERSION",
+      "changelog-path": "CHANGELOG.md",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true
+    }
+  },
+  "changelog-sections": [
+    { "type": "feat", "section": "Features" },
+    { "type": "fix", "section": "Bug Fixes" },
+    { "type": "perf", "section": "Performance" },
+    { "type": "refactor", "section": "Code Refactoring", "hidden": true },
+    { "type": "docs", "section": "Documentation", "hidden": true },
+    { "type": "chore", "section": "Miscellaneous", "hidden": true },
+    { "type": "test", "section": "Tests", "hidden": true }
+  ]
+}
diff --git a/project-templates/release-please-manifest.json b/project-templates/release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+  ".": "0.1.0"
+}
diff --git a/project-templates/release-please.yml b/project-templates/release-please.yml
@@ -0,0 +1,22 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      version: ${{ steps.release.outputs.version }}
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
