Skip to content

Commit 3f82a54

Browse files
mdhellermdheller
committed
Align release checklist with Linux-first native packages
1 parent 136b7c7 commit 3f82a54

1 file changed

Lines changed: 101 additions & 61 deletions

File tree

‎docs/sourceos/RELEASE_CHECKLIST.md‎

Lines changed: 101 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -2,59 +2,67 @@
22

33
## Goal
44

5-
Publish TurtleTerm so users can install it easily on macOS and Linux.
5+
Publish TurtleTerm so Linux users can install, launch, verify, and audit it easily.
66

7-
The intended public path is:
7+
TurtleTerm is Linux-first. macOS remains a compatibility lane, but macOS signing, notarization, DMG/PKG packaging, and Gatekeeper validation are deferred.
8+
9+
Primary Linux install lanes:
810

911
```bash
1012
brew install SourceOS-Linux/tap/turtle-term
1113
```
1214

13-
Windows packaging is postponed until the Homebrew lane is stable.
14-
15-
## Pre-release validation
16-
17-
1. Confirm the repo README introduces TurtleTerm and preserves WezTerm attribution.
18-
2. Confirm `LICENSE.md` is present.
19-
3. Confirm the Homebrew formula is `packaging/homebrew/Formula/turtle-term.rb`.
20-
4. Confirm the stale `sourceos-wezterm.rb` formula is absent.
21-
5. Confirm the release workflow exists at `.github/workflows/turtle-term-release.yml`.
22-
6. Confirm the Homebrew validation workflow exists at `.github/workflows/turtle-term-homebrew.yml`.
23-
7. Confirm script checks exist at `.github/workflows/turtle-term-scripts.yml`.
24-
8. Run the SourceOS wrapper smoke test locally or in CI:
25-
2615
```bash
27-
python3 assets/sourceos/tests/test_sourceos_term_smoke.py
16+
sudo dpkg -i turtle-term_<version>_<arch>.deb
2817
```
2918

30-
9. Run local Homebrew install validation:
19+
```bash
20+
sudo rpm -i turtle-term-<version>-*.rpm
21+
```
3122

3223
```bash
33-
brew install --HEAD ./packaging/homebrew/Formula/turtle-term.rb
34-
brew test turtle-term
35-
turtle-term run -- echo turtle-term-ok
24+
sudo pacman -U turtle-term-<version>-1-<arch>.pkg.tar.zst
3625
```
3726

38-
## First public tap release
27+
Windows packaging is postponed.
3928

40-
Create `SourceOS-Linux/homebrew-tap` if it does not already exist.
29+
## Pre-release validation
4130

42-
Copy staged files into the tap:
31+
1. Confirm the repo README presents TurtleTerm as the product.
32+
2. Confirm `LICENSE.md` and `THIRD_PARTY_NOTICES.md` are present.
33+
3. Confirm stale `sourceos-wezterm.rb` formula is absent.
34+
4. Confirm the release workflow exists at `.github/workflows/turtle-term-release.yml`.
35+
5. Confirm the native Linux package workflow exists at `.github/workflows/turtle-term-native-linux-packages.yml`.
36+
6. Confirm the Linux packaging validation workflow exists at `.github/workflows/turtle-term-linux-packaging.yml`.
37+
7. Confirm script checks exist at `.github/workflows/turtle-term-scripts.yml`.
38+
8. Run local product and package guards:
4339

44-
```text
45-
packaging/homebrew/Formula/turtle-term.rb -> Formula/turtle-term.rb
46-
packaging/homebrew/README.md -> README.md
47-
packaging/homebrew/.github/workflows/test-formula.yml -> .github/workflows/test-formula.yml
48-
packaging/homebrew/.github/workflows/bottle-formula.yml -> .github/workflows/bottle-formula.yml
40+
```bash
41+
python3 assets/sourceos/tests/test_sourceos_term_smoke.py
42+
python3 assets/sourceos/tests/test_turtle_product_identity.py
43+
python3 assets/sourceos/tests/test_turtle_linux_desktop_identity.py
44+
python3 assets/sourceos/tests/test_turtle_linux_native_packaging.py
45+
python3 assets/sourceos/tests/test_turtle_neovim_integration.py
46+
python3 assets/sourceos/tests/test_turtle_term_release_readiness.py
4947
```
5048

51-
Push the tap.
49+
9. Run Linux package layout validation:
5250

53-
Validate public install:
51+
```bash
52+
bash packaging/scripts/verify-linux-package-layout.sh
53+
bash packaging/scripts/verify-deb-package.sh
54+
bash packaging/scripts/verify-rpm-package.sh
55+
bash packaging/scripts/verify-arch-package.sh
56+
```
57+
58+
10. Run local Homebrew install validation where Homebrew is available:
5459

5560
```bash
56-
brew install --HEAD SourceOS-Linux/tap/turtle-term
61+
brew install --HEAD ./packaging/homebrew/Formula/turtle-term.rb
62+
brew test turtle-term
63+
turtleterm --version || true
5764
turtle-term run -- echo turtle-term-ok
65+
turtle-agentctl --stdio ping
5866
```
5967

6068
## Release artifact publication
@@ -66,65 +74,97 @@ git tag turtle-term-v0.1.0
6674
git push origin turtle-term-v0.1.0
6775
```
6876

69-
The release workflow builds:
77+
The release workflows should publish:
7078

71-
- macOS ARM64 tarball
72-
- macOS Intel tarball
7379
- Linux x86_64 tarball
7480
- Linux ARM64 tarball
81+
- macOS ARM64 tarball, unsigned compatibility artifact
82+
- macOS Intel tarball, unsigned compatibility artifact
83+
- Debian packages for amd64 and arm64
84+
- RPM packages for x86_64 and aarch64
85+
- Arch packages for x86_64 and aarch64
7586
- SHA-256 checksum files
76-
- Release manifest JSON files
87+
- Package manifest JSON files
88+
- Native package index JSON
89+
- SPDX SBOMs
90+
- GitHub artifact attestations
7791

78-
Artifacts are attached to the GitHub release for the tag. Every tarball should have:
92+
Every tarball should have:
7993

8094
```text
8195
*.tar.gz
8296
*.tar.gz.sha256
8397
*.tar.gz.manifest.json
8498
```
8599

86-
## Stable Homebrew formula promotion
87-
88-
After a release tag exists, render a stable formula from the release source archive SHA:
100+
Every native package should have:
89101

90-
```bash
91-
python3 packaging/scripts/render-stable-homebrew-formula.py turtle-term-v0.1.0 <source_sha256>
102+
```text
103+
*.deb | *.rpm | *.pkg.tar.zst
104+
*.sha256
105+
*.manifest.json
92106
```
93107

94-
The workflow `.github/workflows/turtle-term-promote-homebrew-stable.yml` can compute the source archive SHA and sync the stable formula to the tap when `TURTLE_TERM_TAP_TOKEN` is configured.
108+
The native package set should have:
109+
110+
```text
111+
turtle-term-native-packages.index.json
112+
turtle-term-native-packages.index.json.sha256
113+
```
95114

96-
## Bottle milestone
115+
## First public tap release
97116

98-
After HEAD formula CI is green on macOS and Linux, build Homebrew bottles in the tap.
117+
Create `SourceOS-Linux/homebrew-tap` if it does not already exist.
99118

100-
The staged tap workflow is:
119+
Copy staged files into the tap:
101120

102121
```text
103-
packaging/homebrew/.github/workflows/bottle-formula.yml
122+
packaging/homebrew/Formula/turtle-term.rb -> Formula/turtle-term.rb
123+
packaging/homebrew/README.md -> README.md
124+
packaging/homebrew/.github/workflows/test-formula.yml -> .github/workflows/test-formula.yml
125+
packaging/homebrew/.github/workflows/bottle-formula.yml -> .github/workflows/bottle-formula.yml
126+
```
127+
128+
Push the tap.
129+
130+
Validate public install:
131+
132+
```bash
133+
brew install --HEAD SourceOS-Linux/tap/turtle-term
134+
turtleterm --version || true
135+
turtle-term run -- echo turtle-term-ok
104136
```
105137

106-
The goal is to move from source builds to fast installs:
138+
## Stable Homebrew formula promotion
139+
140+
After a release tag exists, render a stable formula from the release source archive SHA:
107141

108142
```bash
109-
brew install turtle-term
143+
python3 packaging/scripts/render-stable-homebrew-formula.py turtle-term-v0.1.0 <source_sha256>
110144
```
111145

146+
The workflow `.github/workflows/turtle-term-promote-homebrew-stable.yml` can compute the source archive SHA and sync the stable formula to the tap when `TURTLE_TERM_TAP_TOKEN` is configured.
147+
112148
## Acceptance criteria for v0 public availability
113149

114-
1. `brew install --HEAD SourceOS-Linux/tap/turtle-term` works on macOS ARM64.
115-
2. `brew install --HEAD SourceOS-Linux/tap/turtle-term` works on macOS Intel.
116-
3. `brew install --HEAD SourceOS-Linux/tap/turtle-term` works on Linux x86_64.
117-
4. `brew install --HEAD SourceOS-Linux/tap/turtle-term` works on Linux ARM64.
118-
5. `turtle-term paths` works.
119-
6. `turtle-term run -- echo hello` emits events and receipts.
120-
7. `sourceos-term paths` still works.
121-
8. A `turtle-term-v0.1.0` release publishes tarballs, checksums, and manifests.
122-
9. README and formula both use TurtleTerm as the public product name.
150+
1. `turtleterm` launches TurtleTerm.
151+
2. `turtle-term run -- echo turtle-term-ok` emits events and receipts.
152+
3. `turtle-agentctl --stdio ping` works.
153+
4. Linux desktop metadata validates.
154+
5. AppStream metadata validates.
155+
6. Debian, RPM, and Arch packages build with private runtime under `/usr/libexec/turtle-term`.
156+
7. Native packages install the profile at `/etc/turtle-term/turtleterm.lua`.
157+
8. Native package wrappers do not contain buildroot paths.
158+
9. Native packages include checksums and manifests.
159+
10. Native package index is published and attested.
160+
11. Release tarballs include checksums, manifests, SBOMs, and attestations.
161+
12. README, formulae, metadata, and packages use TurtleTerm as the public product name.
123162

124163
## Post-v0 hardening
125164

126-
1. Add stable release tarball URL and SHA-256 to the formula.
127-
2. Publish bottles.
165+
1. Publish Homebrew bottles.
166+
2. Add repository metadata for apt/yum/dnf/pacman distribution channels.
128167
3. Add upgrade/rollback docs.
129-
4. Add Chocolatey, WinGet, or Scoop planning for Windows.
130-
5. Add distro-native packaging for SourceOS Linux images.
168+
4. Add SourceOS image integration.
169+
5. Add Windows packaging plan.
170+
6. Revisit macOS signing/notarization after Linux distribution is stable.

0 commit comments

Comments
 (0)