Updates
This commit is contained in:
Raven Scott
+81
-82
@@ -1,106 +1,105 @@
|
||||
# Release process
|
||||
|
||||
## Preconditions
|
||||
## Host matrix
|
||||
|
||||
- [ ] `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
|
||||
| Product | Toolchain | Hosts |
|
||||
|---------|-----------|-------|
|
||||
| **Server** | Bare standalone (`scripts/bare-standalone.cjs`) | **`linux-x64`**, **`linux-arm64` only** |
|
||||
| **Client** | Electron Forge (`forge.config.cjs`) | `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`, `win32-x64`, `win32-arm64` |
|
||||
|
||||
## Version & tag
|
||||
Same layout as PearDock’s rolling pipeline, except PearData agents ship **Linux-only**.
|
||||
|
||||
## Local builds
|
||||
|
||||
```bash
|
||||
# 1. Bump version in package.json (semver)
|
||||
# 2. Commit
|
||||
git add package.json
|
||||
git commit -m "Release vX.Y.Z"
|
||||
npm install
|
||||
|
||||
# 3. Tag
|
||||
# Everything CI builds
|
||||
npm run make
|
||||
|
||||
# Or separately
|
||||
npm run make:server # both Linux arches
|
||||
npm run make:server:linux-x64
|
||||
npm run make:client # all client hosts
|
||||
npm run make:client:darwin-arm64
|
||||
|
||||
# Dev Electron UI (not Pear runtime)
|
||||
npm run start:client
|
||||
```
|
||||
|
||||
Outputs land under `out/`:
|
||||
|
||||
```
|
||||
out/peardata-server-linux-x64/peardata-server
|
||||
out/peardata-linux-x64/peardata-client
|
||||
out/peardata-darwin-arm64/peardata.app # macOS
|
||||
```
|
||||
|
||||
Env knobs:
|
||||
|
||||
| Env | Default | Meaning |
|
||||
|-----|---------|---------|
|
||||
| `PEARDATA_SERVER_HOSTS` | `linux-x64,linux-arm64` | Server host list |
|
||||
| `PEARDATA_CLIENT_HOSTS` | all 64-bit | Client host list |
|
||||
| `PEARDATA_SKIP_CLIENT=1` | off | Server-only release |
|
||||
| `PEARDATA_SKIP_REBUILD=1` | on in CI | Skip `@electron/rebuild` |
|
||||
| `DRY_RUN=1` | off | Stage archives, skip upload |
|
||||
|
||||
## CI / forge pipelines
|
||||
|
||||
| Forge | Workflow | Trigger | Output |
|
||||
|-------|----------|---------|--------|
|
||||
| **Gitea** | `.gitea/workflows/release-rolling.yml` | push `main`/`master` + manual | Build matrix → prerelease tag **`rolling`** |
|
||||
| **GitHub** | `.github/workflows/release.yml` | `v*` tags + manual | Same matrix → GitHub Release assets |
|
||||
| Both | `.gitea/workflows/ci.yml` / `.github/workflows/ci.yml` | PR / push | Unit tests |
|
||||
|
||||
Rolling script: [`scripts/gitea-rolling-release.sh`](../scripts/gitea-rolling-release.sh)
|
||||
Orchestrator: [`scripts/make.cjs`](../scripts/make.cjs)
|
||||
Hosts: [`scripts/hosts.cjs`](../scripts/hosts.cjs)
|
||||
|
||||
### Secrets
|
||||
|
||||
| Secret | Used by |
|
||||
|--------|---------|
|
||||
| `RELEASE_TOKEN` | Gitea rolling publish (**required**) |
|
||||
| `GITEA_URL` | Optional forge base URL |
|
||||
| `GITHUB_TOKEN` | GitHub Release (automatic) |
|
||||
|
||||
### macOS codesign
|
||||
|
||||
Darwin **clients** built on Linux are seal-signed with vendored `tools/rcodesign/` (see that README). Avoids Gatekeeper “damaged” false positives. Not notarized unless you set Developer ID credentials.
|
||||
|
||||
## Version & tag (semver)
|
||||
|
||||
```bash
|
||||
# 1. Bump version in package.json
|
||||
# 2. Commit + 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:
|
||||
- **Gitea:** every `main` push republishes `rolling` (latest main binaries).
|
||||
- **GitHub:** `v*` tags upload versioned archives from the release workflow.
|
||||
|
||||
| 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
|
||||
## Source-only tarball (optional)
|
||||
|
||||
```bash
|
||||
bash scripts/release.sh
|
||||
bash scripts/release.sh # dist/peardata-vX.Y.Z.tar.gz (source tree)
|
||||
```
|
||||
|
||||
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.
|
||||
Prefer the binary matrix for operators.
|
||||
|
||||
## 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.
|
||||
1. **Protocol** — RPC / push changes
|
||||
2. **Security** — auth / roles
|
||||
3. **Desktop** — Electron / Pear UI
|
||||
4. **Ops** — env, systemd, collectors
|
||||
5. **Breaking** — re-dial / invite requirements
|
||||
|
||||
## Related
|
||||
|
||||
- [CI.md](./CI.md)
|
||||
- [SECURITY.md](./SECURITY.md)
|
||||
- [CONFIGURATION.md](./CONFIGURATION.md)
|
||||
- [TECH-CHOICES.md](./TECH-CHOICES.md) (Bare import maps)
|
||||
- PearDock reference: `docs/RELEASE.md` in the peardock repo
|
||||
|
||||
Reference in New Issue
Block a user