feat: initial stamp implementation

- stamp add: create .stamp/*.md changeset files (interactive + --no-interactive) - stamp status: show pending stamps and projected next versions (plain + --json) - stamp version: consume stamps, bump semver, update CHANGELOGs, commit - stamp publish: create git tags, GitHub/Gitea releases, upload artifacts - stamp comment: post/update idempotent PR comments via GitHub/Gitea API - Supports monorepos via stamp.toml [[projects]] blocks - Changeset files support YAML (---) and TOML (+++) frontmatter - Semver + pre-release support (alpha, beta, rc) - Examples and workflow documentation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-03-08 20:56:23 +01:00
commit 77462f5e8a
25 changed files with 2518 additions and 0 deletions
--- a/docs/workflow.md
+++ b/docs/workflow.md
@@ -0,0 +1,229 @@
+# stamp — Workflow Guide
+
+`stamp` is a language-agnostic, changesets-style versioning and changelog tool.
+It works with any project type and supports monorepos.
+
+## Concepts
+
+| Term | Description |
+|------|-------------|
+| **Stamp file** | A `.stamp/*.md` file describing a change and which projects it affects |
+| **Bump type** | How to increment a version: `major`, `minor`, `patch`, or pre-release variants |
+| `stamp version` | Consumes stamp files → bumps versions → updates changelogs |
+| `stamp publish` | Creates git tags, releases, and uploads artifacts |
+
+---
+
+## Setup
+
+### 1. Install stamp
+
+Via [Mise](https://mise.jdx.dev/):
+
+```toml
+# mise.toml
+[tools]
+"go:github.com/thokra/stamp/cmd/stamp" = "latest"
+```
+
+Or build from source:
+
+```sh
+go install github.com/thokra/stamp/cmd/stamp@latest
+```
+
+### 2. Create stamp.toml
+
+At the root of your repository:
+
+```toml
+[[projects]]
+name    = "my-app"
+path    = "."
+version = "0.1.0"
+
+  [projects.publish]
+  tags      = true
+  releases  = true
+  artifacts = ["dist/my-app-*"]
+```
+
+See [`examples/stamp.toml`](../examples/stamp.toml) for a fully annotated example.
+
+---
+
+## Day-to-day Workflow
+
+### Adding a stamp to your PR
+
+When making a change that should be released, add a stamp file:
+
+```sh
+# Interactive
+stamp add
+
+# Non-interactive (useful in scripts or with AI agents)
+stamp add --project=my-app --bump=minor --message="Added X feature" --no-interactive
+```
+
+This creates a `.stamp/<random-slug>.md` file, e.g.:
+
+```markdown
+---
+bumps:
+  my-app: minor
+---
+
+Added X feature
+```
+
+Commit and push the stamp file alongside your code changes.
+
+### Checking pending stamps
+
+```sh
+stamp status
+```
+
+```
+📦 Pending stamps: 2
+
+  PROJECT   CURRENT  NEXT   BUMP   STAMPS
+  -------   -------  ----   ----   ------
+  my-app    1.2.3    1.3.0  minor  2
+  my-lib    0.1.0    0.1.0  —      0
+```
+
+### Releasing
+
+On your release branch (e.g. after merging PRs):
+
+```sh
+# 1. Bump versions and update changelogs
+stamp version
+
+# 2. Publish tags, releases, and artifacts
+STAMP_REPO=owner/repo stamp publish
+```
+
+For a pre-release snapshot:
+
+```sh
+stamp version --snapshot=alpha
+stamp publish
+```
+
+---
+
+## PR Commenting (CI)
+
+Use `stamp comment` in your CI pipeline to automatically comment on PRs:
+
+- ⚠️  **No stamp file?** → warns the author and explains how to add one
+- ✅  **Stamps found?** → shows a table of affected projects and next versions
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/stamp-check.yml
+name: stamp check
+
+on:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install stamp
+        run: go install github.com/thokra/stamp/cmd/stamp@latest
+
+      - name: Comment on PR
+        run: stamp comment --pr=${{ github.event.pull_request.number }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          STAMP_REPO:   ${{ github.repository }}
+```
+
+### Gitea Actions
+
+```yaml
+# .gitea/workflows/stamp-check.yml
+name: stamp check
+
+on:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install stamp
+        run: go install github.com/thokra/stamp/cmd/stamp@latest
+
+      - name: Comment on PR
+        run: stamp comment --pr=${{ gitea.event.pull_request.number }}
+        env:
+          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          GITEA_BASE_URL: ${{ gitea.server_url }}
+          STAMP_REPO:     ${{ gitea.repository }}
+```
+
+---
+
+## Stamp File Format
+
+Stamp files live in `.stamp/` and use Markdown with either YAML or TOML frontmatter.
+
+### YAML frontmatter (default)
+
+```markdown
+---
+bumps:
+  my-app: minor
+  my-lib: patch
+---
+
+Short description of the change used as the changelog entry.
+
+- Optional bullet points
+- for more detail
+```
+
+### TOML frontmatter
+
+```markdown
+++
+[bumps]
+my-app = "minor"
+++
+
+Short description.
+```
+
+### Valid bump types
+
+| Type | Description |
+|------|-------------|
+| `major` | Breaking change (1.x.x → 2.0.0) |
+| `minor` | New feature (1.2.x → 1.3.0) |
+| `patch` | Bug fix (1.2.3 → 1.2.4) |
+| `premajor` | Pre-release major (→ 2.0.0-alpha.0) |
+| `preminor` | Pre-release minor (→ 1.3.0-beta.0) |
+| `prepatch` | Pre-release patch (→ 1.2.4-rc.0) |
+| `prerelease` | Increment pre-release (1.2.4-rc.0 → 1.2.4-rc.1) |
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `STAMP_REPO` | Repository slug `owner/repo` used by publish and comment |
+| `GITHUB_TOKEN` | GitHub personal access token for releases and PR comments |
+| `GITEA_TOKEN` | Gitea access token |
+| `GITEA_BASE_URL` | Gitea instance URL (e.g. `https://gitea.example.com`) — also used to detect Gitea mode |