# Releasing

How to cut a new release and tag it on tangled.org.

## Before you release

1. **Update `CHANGELOG.md`** — move everything under `[Unreleased]` into a new versioned section:

   ```markdown
   ## [0.2.0] - YYYY-MM-DD
   ```

   Update the comparison links at the bottom of the file.

2. **Commit the changelog:**

   ```
   jj commit -m "chore: release v0.2.0"
   ```

3. **Push to main:**

   ```
   jj git push
   ```

## Tagging

jj only creates lightweight tags. For release notes to appear on tangled.org, use an **annotated** git tag instead:

```bash
git tag -a v0.2.0 -m "Release v0.2.0

<paste the changelog entry here>"
```

Then push the tag:

```bash
jj git push --tag v0.2.0
```

The tag will appear on tangled.org under your repository's tags/releases page.

## Versioning

This project uses [Semantic Versioning](https://semver.org/):

- **Patch** (`0.1.x`) — bug fixes, dependency updates, documentation
- **Minor** (`0.x.0`) — new features, config changes that are backwards compatible
- **Major** (`x.0.0`) — breaking changes (e.g. incompatible config format, changed volume layout)

## Updating pinned versions

When upgrading a dependency, update both the tag/version **and** the digest in the relevant file:

| Dependency | File | What to update |
|------------|------|----------------|
| OpenBao | `docker-compose.yml` | image tag + `@sha256:...` |
| Go builder | `Dockerfile` | `FROM golang:X.Y.Z-alpineA.B@sha256:...` |
| Alpine runtime | `Dockerfile` | `FROM alpine:X.Y.Z@sha256:...` |
| Spindle source | `Dockerfile` | `--branch vX.Y.Z` + commit SHA in the verify step |

To find a new SHA256 digest:

```bash
# Docker Hub images
curl -s "https://hub.docker.com/v2/repositories/library/alpine/tags/3.23.3" | python3 -c "import sys,json; print(json.load(sys.stdin)['digest'])"

# Quay.io images
curl -s "https://quay.io/api/v1/repository/openbao/openbao/tag/?specificTag=2.5.2" | python3 -c "import sys,json; [print(t['manifest_digest']) for t in json.load(sys.stdin)['tags']]"

# Spindle commit SHA
git ls-remote https://tangled.org/tangled.org/core refs/tags/vX.Y.Z-alpha
```