stamp/docs/workflow.md

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:

# mise.toml
[tools]
"go:git.thokra.dev/thokra/stamp/cmd/stamp" = "latest"

Or build from source:

go install git.thokra.dev/thokra/stamp/cmd/stamp@latest

2. Create stamp.toml

At the root of your repository:

[[projects]]
name    = "my-app"
path    = "."
version = "0.1.0"

  [projects.publish]
  tags      = true
  releases  = true
  artifacts = ["dist/my-app-*"]

See 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:

# 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.:

---
bumps:
  my-app: minor
---

Added X feature

Commit and push the stamp file alongside your code changes.

Checking pending stamps

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):

# 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:

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

# .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 git.thokra.dev/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

# .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 git.thokra.dev/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)

---
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

+++
[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