danieldaum.net
configuration for self hosting a spindle in docker
1# Releasing
2
3How to cut a new release and tag it on tangled.org.
4
5## Before you release
6
71. **Update `CHANGELOG.md`** — move everything under `[Unreleased]` into a new versioned section:
8
9 ```markdown
10 ## [0.2.0] - YYYY-MM-DD
11 ```
12
13 Update the comparison links at the bottom of the file.
14
152. **Commit the changelog:**
16
17 ```
18 jj commit -m "chore: release v0.2.0"
19 ```
20
213. **Push to main:**
22
23 ```
24 jj git push
25 ```
26
27## Tagging
28
29jj only creates lightweight tags. For release notes to appear on tangled.org, use an **annotated** git tag instead:
30
31```bash
32git tag -a v0.2.0 -m "Release v0.2.0
33
34<paste the changelog entry here>"
35```
36
37Then push the tag:
38
39```bash
40jj git push --tag v0.2.0
41```
42
43The tag will appear on tangled.org under your repository's tags/releases page.
44
45## Versioning
46
47This project uses [Semantic Versioning](https://semver.org/):
48
49- **Patch** (`0.1.x`) — bug fixes, dependency updates, documentation
50- **Minor** (`0.x.0`) — new features, config changes that are backwards compatible
51- **Major** (`x.0.0`) — breaking changes (e.g. incompatible config format, changed volume layout)
52
53## Updating pinned versions
54
55When upgrading a dependency, update both the tag/version **and** the digest in the relevant file:
56
57| Dependency | File | What to update |
58|------------|------|----------------|
59| OpenBao | `docker-compose.yml` | image tag + `@sha256:...` |
60| Go builder | `Dockerfile` | `FROM golang:X.Y.Z-alpineA.B@sha256:...` |
61| Alpine runtime | `Dockerfile` | `FROM alpine:X.Y.Z@sha256:...` |
62| Spindle source | `Dockerfile` | `--branch vX.Y.Z` + commit SHA in the verify step |
63
64To find a new SHA256 digest:
65
66```bash
67# Docker Hub images
68curl -s "https://hub.docker.com/v2/repositories/library/alpine/tags/3.23.3" | python3 -c "import sys,json; print(json.load(sys.stdin)['digest'])"
69
70# Quay.io images
71curl -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']]"
72
73# Spindle commit SHA
74git ls-remote https://tangled.org/tangled.org/core refs/tags/vX.Y.Z-alpha
75```