first commit

2026-07-18 16:17:38 -04:00
commit 015d92a257
70 changed files with 10033 additions and 0 deletions
@@ -0,0 +1,106 @@
+# Release process
+
+## Preconditions
+
+- [ ] `npm test` passes (use `SKIP_INTEGRATION=1` only if the runner cannot do DHT)
+- [ ] Version bumped in `package.json`
+- [ ] Docs updated if protocol / env / UX changed
+- [ ] No secrets in the tree (`.env`, `data/`, identity files)
+- [ ] `git status` clean except intended changes
+
+## Version & tag
+
+```bash
+# 1. Bump version in package.json (semver)
+# 2. Commit
+git add package.json
+git commit -m "Release vX.Y.Z"
+
+# 3. Tag
+git tag -a vX.Y.Z -m "vX.Y.Z"
+
+# 4. Push
+git push origin main
+git push origin vX.Y.Z
+```
+
+Tag pattern **`v*`** triggers versioned GitHub releases. On Gitea, **every push to `main`/`master`** rebuilds the rolling release:
+
+| Forge | Workflow | Trigger | Output |
+|-------|----------|---------|--------|
+| GitHub | `.github/workflows/release.yml` | `v*` tags / manual | Source tarball + sha256 → GitHub Release |
+| Gitea | `.gitea/workflows/release-rolling.yml` | push to `main`/`master` / manual | `scripts/gitea-rolling-release.sh` → prerelease tag **`rolling`** |
+
+The rolling job always runs after a successful install+test on the default branch. It deletes and recreates the `rolling` tag/release so operators can always download the latest main build.
+
+## Local artifacts
+
+```bash
+bash scripts/release.sh
+```
+
+Produces:
+
+```
+dist/
+├── peardata-vX.Y.Z.tar.gz
+├── peardata-vX.Y.Z.tar.gz.sha256
+└── RELEASE_NOTES.md
+```
+
+Verify:
+
+```bash
+cd dist
+sha256sum -c peardata-vX.Y.Z.tar.gz.sha256
+# or: shasum -a 256 -c …
+```
+
+Tarball **excludes** `node_modules/`, `.git/`, `data/`, `dist/`.
+
+## What ships
+
+| Included | Not included |
+|----------|--------------|
+| Source (server, client, shared, UI) | `node_modules` |
+| CI workflows | `.env` / secrets |
+| Docs + systemd unit | Runtime `data/` |
+| Scripts | Generated release dist |
+
+Consumers install with `npm install` after unpacking.
+
+## Changelog guidance
+
+For each release note:
+
+1. **Protocol** — method / push / version bumps
+2. **Security** — auth or default role changes
+3. **Desktop** — pear-ctrl / window / Pear dependency bumps
+4. **Ops** — env vars, systemd, healthcheck
+5. **Breaking** — call out re-dial / re-invite requirements
+
+## Hotfix without retag
+
+Push commits to `main` for CI only. Prefer a new patch tag for anything operators must download.
+
+## Rollback
+
+- **App code**: redeploy previous tag tarball / checkout
+- **Server seed**: only if compromised — generate new seed (new public key); re-issue all invites; clients must dial the new key
+- **Peer policy**: restore `data/peer-policy.json` from backup if revoke tables were corrupted
+
+## Secrets for forges
+
+| Secret | Where | Purpose |
+|--------|-------|---------|
+| `GITHUB_TOKEN` | GitHub (automatic) | Upload release assets |
+| `RELEASE_TOKEN` | Gitea (**required**) | Publish/update `rolling` release |
+| `GITEA_URL` | Gitea (optional) | Forge API base (defaults from runner) |
+
+Never put `SERVER_SEED` in CI secrets unless a dedicated deploy job needs it — prefer generating seeds on the target host.
+
+## Related
+
+- [CI.md](./CI.md)
+- [SECURITY.md](./SECURITY.md)
+- [CONFIGURATION.md](./CONFIGURATION.md)