Stamp
This commit is contained in:
Thomas
309
README.md
Normal file
309
README.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# stamp
|
||||
|
||||
A language-agnostic, changesets-style versioning and changelog tool. Works with any project type and supports monorepos.
|
||||
|
||||
## Overview
|
||||
|
||||
`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.
|
||||
|
||||
## Installation
|
||||
|
||||
Via [Mise](https://mise.jdx.dev/):
|
||||
|
||||
```toml
|
||||
# mise.toml
|
||||
[tools]
|
||||
"go:github.com/thokra/stamp/cmd/stamp" = "latest"
|
||||
```
|
||||
|
||||
Or with `go install`:
|
||||
|
||||
```sh
|
||||
go install github.com/thokra/stamp/cmd/stamp@latest
|
||||
```
|
||||
|
||||
Or build from source:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/thokra/stamp
|
||||
cd stamp
|
||||
go build -o bin/stamp ./cmd/stamp
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. 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.
|
||||
|
||||
### 2. Add a stamp file when making a change
|
||||
|
||||
```sh
|
||||
# Interactive
|
||||
stamp add
|
||||
|
||||
# Non-interactive (great for scripts and AI agents)
|
||||
stamp add --project=my-app --bump=minor --message="Added new feature"
|
||||
```
|
||||
|
||||
This creates a `.stamp/<random-slug>.md` file. Commit it alongside your code.
|
||||
|
||||
### 3. Check pending stamps
|
||||
|
||||
```sh
|
||||
stamp status
|
||||
```
|
||||
|
||||
```
|
||||
📦 Pending stamps: 2
|
||||
|
||||
PROJECT CURRENT NEXT BUMP STAMPS
|
||||
------- ------- ---- ---- ------
|
||||
my-app 1.2.3 1.3.0 minor 2
|
||||
```
|
||||
|
||||
### 4. Release
|
||||
|
||||
```sh
|
||||
# Bump versions and update changelogs
|
||||
stamp version
|
||||
|
||||
# Create git tags, GitHub/Gitea releases, and upload artifacts
|
||||
STAMP_REPO=owner/repo stamp publish
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `stamp add`
|
||||
|
||||
Creates a new stamp file describing a change.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--project` | Project name to include (repeatable) |
|
||||
| `--bump` | Bump type: `major`, `minor`, `patch`, `premajor`, `preminor`, `prepatch`, `prerelease` |
|
||||
| `--message` | Description of the change |
|
||||
| `--no-interactive` | Disable interactive prompts (requires `--project`, `--bump`, `--message`) |
|
||||
| `--slug` | Custom filename slug (default: auto-generated, e.g. `brave-river`) |
|
||||
|
||||
### `stamp status`
|
||||
|
||||
Shows all pending stamp files and the projected next version for each project.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--json` | Output as JSON |
|
||||
|
||||
### `stamp version`
|
||||
|
||||
Consumes all pending stamp files, bumps versions in `stamp.toml`, and prepends a new entry to each project's `CHANGELOG.md`. Then stages and commits the changes via git.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--snapshot <id>` | Create a pre-release with the given identifier (e.g. `alpha`, `rc`) |
|
||||
| `--no-commit` | Apply changes without creating a git commit |
|
||||
|
||||
### `stamp publish`
|
||||
|
||||
Creates git tags and publishes releases (with optional artifact uploads) to GitHub or Gitea.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--dry-run` / `-n` | Print what would happen without executing |
|
||||
| `--project` | Only publish a specific project |
|
||||
|
||||
Requires `STAMP_REPO=owner/repo` to be set. Detects GitHub vs Gitea automatically via the `GITEA_BASE_URL` environment variable.
|
||||
|
||||
Tag format: `<name>@v<version>` (e.g. `my-app@v1.3.0`).
|
||||
|
||||
### `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.
|
||||
|
||||
- **No stamps found** → warns the author with instructions on how to add one.
|
||||
- **Stamps found** → shows a table of affected projects and their next versions.
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--pr` | Pull request number (required) |
|
||||
| `--repo` | Repository slug `owner/repo` (defaults to `STAMP_REPO` or `GITHUB_REPOSITORY`) |
|
||||
|
||||
## Stamp File Format
|
||||
|
||||
Stamp files live in `.stamp/` and use Markdown with YAML or TOML frontmatter.
|
||||
|
||||
### YAML (default)
|
||||
|
||||
```markdown
|
||||
---
|
||||
bumps:
|
||||
my-app: minor
|
||||
my-lib: patch
|
||||
---
|
||||
|
||||
Short description used as the changelog entry.
|
||||
|
||||
- Optional bullet points for more detail.
|
||||
```
|
||||
|
||||
### TOML
|
||||
|
||||
```markdown
|
||||
+++
|
||||
[bumps]
|
||||
my-app = "minor"
|
||||
+++
|
||||
|
||||
Short description.
|
||||
```
|
||||
|
||||
### Bump types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `major` | Breaking change — `1.2.3` → `2.0.0` |
|
||||
| `minor` | New feature — `1.2.3` → `1.3.0` |
|
||||
| `patch` | Bug fix — `1.2.3` → `1.2.4` |
|
||||
| `premajor` | Pre-release major — `1.2.3` → `2.0.0-alpha.0` |
|
||||
| `preminor` | Pre-release minor — `1.2.3` → `1.3.0-alpha.0` |
|
||||
| `prepatch` | Pre-release patch — `1.2.3` → `1.2.4-alpha.0` |
|
||||
| `prerelease` | Increment pre-release — `1.2.4-rc.0` → `1.2.4-rc.1` |
|
||||
|
||||
## Configuration Reference (`stamp.toml`)
|
||||
|
||||
```toml
|
||||
# Global settings (all optional)
|
||||
[config]
|
||||
base_branch = "main" # Base branch for PR change detection (default: main)
|
||||
changeset_dir = ".stamp" # Directory for stamp files (default: .stamp)
|
||||
|
||||
[[projects]]
|
||||
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)
|
||||
|
||||
[projects.publish]
|
||||
tags = true
|
||||
releases = true
|
||||
artifacts = [
|
||||
"apps/my-app/dist/my-app-linux-amd64",
|
||||
"apps/my-app/dist/my-app-darwin-arm64",
|
||||
]
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `STAMP_REPO` | Repository slug `owner/repo` — required for `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 enables Gitea mode |
|
||||
|
||||
## CI Integration
|
||||
|
||||
### GitHub Actions — PR check
|
||||
|
||||
```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 — PR check
|
||||
|
||||
```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 }}
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
This project uses [Mise](https://mise.jdx.dev/) to manage the Go toolchain and common tasks.
|
||||
|
||||
```sh
|
||||
# Build
|
||||
mise run build
|
||||
|
||||
# Run tests
|
||||
mise run test
|
||||
|
||||
# Lint
|
||||
mise run lint
|
||||
|
||||
# Install locally
|
||||
mise run install
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
stamp/
|
||||
├── cmd/stamp/ # CLI entry point and command definitions
|
||||
├── internal/
|
||||
│ ├── 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)
|
||||
│ ├── publish/ # Orchestrates tagging and release publishing
|
||||
│ └── semver/ # Semantic version bumping logic
|
||||
├── examples/
|
||||
│ └── stamp.toml # Annotated configuration example
|
||||
└── docs/
|
||||
└── workflow.md # Detailed workflow guide
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user