thokra/stamp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Release

Browse Source
This commit is contained in:
Thomas
2026-03-12 23:41:12 +01:00
parent 8049c505a0
commit 7c1a20465a
10 changed files with 1057 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

245
README.md
View File

@@ -6,6 +6,11 @@ A language-agnostic, changesets-style versioning and changelog tool. Works with
`stamp` is inspired by the [Changesets](https://github.com/changesets/changesets) workflow, but without the Node.js dependency. It works by having contributors add small **stamp files** (`.stamp/*.md`) alongside their code changes. When it's time to release, `stamp` consumes those files, bumps versions, updates changelogs, creates git tags, and publishes releases to GitHub or Gitea.
There are two supported release workflows:
- **Direct release** — run `stamp version` and `stamp publish` locally or in CI on the base branch.
- **Release PR** — run `stamp release-pr` in CI to open a pull request that contains the version bumps. Merging the PR triggers the actual publish step.
## Installation
Via [Mise](https://mise.jdx.dev/):
@@ -13,19 +18,19 @@ Via [Mise](https://mise.jdx.dev/):
```toml
# mise.toml
[tools]
"go:github.com/thokra/stamp/cmd/stamp" = "latest"
"go:git.thokra.dev/thokra/stamp/cmd/stamp" = "latest"
```
Or with `go install`:
```sh
go install github.com/thokra/stamp/cmd/stamp@latest
go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
```
Or build from source:
```sh
git clone https://github.com/thokra/stamp
git clone https://git.thokra.dev/thokra/stamp
cd stamp
go build -o bin/stamp ./cmd/stamp
```
@@ -130,6 +135,27 @@ Requires `STAMP_REPO=owner/repo` to be set. Detects GitHub vs Gitea automaticall
Tag format: `<name>@v<version>` (e.g. `my-app@v1.3.0`).
### `stamp release-pr`
Creates or updates a **release pull request** — a PR that contains all the version bumps and changelog updates that would be applied by `stamp version`. Merging it acts as the explicit release trigger.
The command:
1. Reads all pending stamp files. If there are none, it exits cleanly with no side effects.
2. Fetches `origin` and resets a well-known branch (default: `stamp/release`) from the tip of the base branch, so the branch is always a clean, fast-forwardable head.
3. Applies all version bumps and changelog updates to that branch (identical logic to `stamp version --no-commit`), then commits and force-pushes it.
4. Opens a new PR — or updates the existing one — targeting the base branch. The PR is identified across runs by a hidden marker in the body, so only one stamp release PR exists at a time.
Once the PR is merged, run `stamp publish` to tag and release.
| Flag | Description |
|------|-------------|
| `--branch` | Release branch name (default: `stamp/release`) |
| `--base` | Base branch the PR targets (default: from `stamp.toml`, fallback: `main`) |
| `--repo` | Repository slug `owner/repo` (defaults to `STAMP_REPO` or `GITHUB_REPOSITORY`) |
| `--snapshot <id>` | Pre-release identifier (e.g. `alpha`, `rc`) |
| `--dry-run` / `-n` | Print what would be done without pushing or opening a PR |
### `stamp comment`
Posts or updates a PR comment summarising pending stamps. Useful in CI to remind contributors to add stamp files or to show reviewers what versions will change.
@@ -142,6 +168,18 @@ Posts or updates a PR comment summarising pending stamps. Useful in CI to remind
| `--pr` | Pull request number (required) |
| `--repo` | Repository slug `owner/repo` (defaults to `STAMP_REPO` or `GITHUB_REPOSITORY`) |
### `stamp preview`
Manages **pre-release mode** for a project. While a project is in pre-release mode, every `stamp version` (and `stamp release-pr`) run produces pre-release versions (e.g. `1.3.0-beta.0`, `1.3.0-beta.1`) instead of normal ones. Exiting preview mode causes the next run to produce a regular release.
```sh
# Enter pre-release mode — all future version bumps will be pre-releases
stamp preview enter my-app beta
# Leave pre-release mode — the next version bump will be a normal release
stamp preview exit my-app
```
## Stamp File Format
Stamp files live in `.stamp/` alongside `stamp.toml`, and use Markdown with YAML or TOML frontmatter.
@@ -195,6 +233,7 @@ name = "my-app"
path = "apps/my-app" # Path relative to repo root
version = "1.2.3" # Current version — updated by `stamp version`
changelog = "CHANGELOG.md" # Relative to path (default: CHANGELOG.md)
pre_tag = "" # Set by `stamp preview enter`; leave blank for normal releases
[projects.publish]
tags = true
@@ -209,14 +248,18 @@ changelog = "CHANGELOG.md" # Relative to path (default: CHANGELOG.md)
| Variable | Purpose |
|----------|---------|
| `STAMP_REPO` | Repository slug `owner/repo` — required for `publish` and `comment` |
| `STAMP_REPO` | Repository slug `owner/repo` — required for `publish`, `comment`, and `release-pr` |
| `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** (Gitea Actions does not inject one automatically); 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 enables Gitea mode |
## CI Integration
### GitHub Actions — PR check
### Workflow: PR check (`stamp comment`)
Posts a comment on every pull request showing which projects will be bumped and to what version. Warns if no stamp file was added.
**GitHub Actions**
```yaml
# .github/workflows/stamp-check.yml
@@ -232,7 +275,7 @@ jobs:
- uses: actions/checkout@v4
- name: Install stamp
run: go install github.com/thokra/stamp/cmd/stamp@latest
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Comment on PR
run: stamp comment --pr=${{ github.event.pull_request.number }}
@@ -241,7 +284,7 @@ jobs:
STAMP_REPO: ${{ github.repository }}
```
### Gitea Actions — PR check
**Gitea Actions**
```yaml
# .gitea/workflows/stamp-check.yml
@@ -257,7 +300,7 @@ jobs:
- uses: actions/checkout@v4
- name: Install stamp
run: go install github.com/thokra/stamp/cmd/stamp@latest
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Comment on PR
run: stamp comment --pr=${{ gitea.event.pull_request.number }}
@@ -267,6 +310,181 @@ jobs:
STAMP_REPO: ${{ gitea.repository }}
```
---
### Workflow: Release PR (`stamp release-pr` + `stamp publish`)
This is the recommended automation workflow. Whenever a PR with stamp files is merged to the base branch, CI opens (or updates) a release PR. Merging the release PR triggers the actual publish.
```
feature branch ──► merge to main ──► stamp release-pr ──► release PR
│
merge to main
│
stamp publish ──► tags + releases
```
**Step 1 — Open or update the release PR on every push to `main`**
*GitHub Actions*
```yaml
# .github/workflows/stamp-release-pr.yml
name: release PR
on:
push:
branches: [main]
jobs:
release-pr:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
# A full clone is needed so stamp can fetch and reset the release branch.
fetch-depth: 0
- name: Install stamp
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Create or update release PR
run: stamp release-pr --base=main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
STAMP_REPO: ${{ github.repository }}
```
*Gitea Actions*
```yaml
# .gitea/workflows/stamp-release-pr.yml
name: release PR
on:
push:
branches: [main]
jobs:
release-pr:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install stamp
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Create or update release PR
run: stamp release-pr --base=main
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
GITEA_BASE_URL: ${{ gitea.server_url }}
STAMP_REPO: ${{ gitea.repository }}
```
**Step 2 — Publish after the release PR is merged**
*GitHub Actions*
```yaml
# .github/workflows/stamp-publish.yml
name: publish
on:
push:
branches: [main]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install stamp
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Publish releases
run: stamp publish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
STAMP_REPO: ${{ github.repository }}
```
*Gitea Actions*
```yaml
# .gitea/workflows/stamp-publish.yml
name: publish
on:
push:
branches: [main]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install stamp
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Publish releases
run: stamp publish
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
GITEA_BASE_URL: ${{ gitea.server_url }}
STAMP_REPO: ${{ gitea.repository }}
```
> **Tip:** Both jobs run on every push to `main`. `stamp release-pr` is a no-op once there are no more pending stamp files (i.e. after the release PR has been merged and `stamp publish` has consumed them). `stamp publish` is a no-op if there are no new tags to create. The two jobs are safe to run in parallel or in sequence.
---
### Workflow: Direct release (no PR)
If you prefer to version and publish in a single step without a release PR, run both commands directly on the base branch:
```yaml
# .github/workflows/stamp-release.yml
name: release
on:
push:
branches: [main]
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Configure git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
- name: Install stamp
run: go install git.thokra.dev/thokra/stamp/cmd/stamp@latest
- name: Version and publish
run: |
stamp version
git push
stamp publish
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
STAMP_REPO: ${{ github.repository }}
```
## Development
This project uses [Mise](https://mise.jdx.dev/) to manage the Go toolchain and common tasks.
@@ -294,17 +512,18 @@ stamp/
│ ├── changeset/ # Stamp file parsing, writing, and slug generation
│ ├── changelog/ # CHANGELOG.md generation and appending
│ ├── config/ # stamp.toml loading, validation, and saving
│ ├── git/ # Git operations (tag, commit, push)
│ ├── gitea/ # Gitea API client (releases, PR comments)
│ ├── github/ # GitHub API client (releases, PR comments)
│ ├── git/ # Git operations (tag, commit, push, branch management)
│ ├── gitea/ # Gitea API client (releases, PR comments, release PRs)
│ ├── github/ # GitHub API client (releases, PR comments, release PRs)
│ ├── publish/ # Orchestrates tagging and release publishing
│ ├── releasepr/ # Orchestrates release PR creation and updates
│ └── semver/ # Semantic version bumping logic
├── examples/
│ └── stamp.toml # Annotated configuration example
└── docs/
└── workflow.md # Detailed workflow guide
└── workflow.md # Detailed workflow guide
```
## License
MIT
MIT