Releasing#

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

Before you release#

Update CHANGELOG.md — move everything under [Unreleased] into a new versioned section:
```
## [0.2.0] - YYYY-MM-DD
```
Update the comparison links at the bottom of the file.
Commit the changelog:
```
jj commit -m "chore: release v0.2.0"
```
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:

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

<paste the changelog entry here>"

Then push the tag:

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:

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:

# 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