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](https://mise.jdx.dev/):

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

Or build from source:

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

### 2. Create .stamp/stamp.toml

Inside the `.stamp/` directory 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-*"]
```

Because `stamp.toml` lives inside `.stamp/`, git will track the directory without needing a `.gitignore` file in it.

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

> Stamp files live alongside `stamp.toml` in the `.stamp/` directory.

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

```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 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/` alongside `stamp.toml`, 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 token for releases and PR comments — automatically provided by the GitHub Actions runner; no manual setup needed |
| `GITEA_TOKEN` | Gitea access token — **must be created manually**; create a token in your Gitea account settings and store it as a repository secret |
| `GITEA_BASE_URL` | Gitea instance URL (e.g. `https://gitea.example.com`) — also used to detect Gitea mode |