Cheng Zhou
142 lines
4.3 KiB
Markdown
142 lines
4.3 KiB
Markdown
# CTMS Web and Desktop Release Guide
|
|
|
|
## Release Unit
|
|
|
|
CTMS uses one repository, one promotion path, and one product version. Web and
|
|
Desktop are build targets from the same source commit, not separately versioned
|
|
products.
|
|
|
|
The release identity consists of:
|
|
|
|
- semantic version, for example `1.8.0`
|
|
- Git tag, for example `v1.8.0`
|
|
- full Git commit SHA
|
|
- build channel: `dev`, `main`, or `release`
|
|
- client type: `web` or `desktop`
|
|
|
|
## Runtime Boundary
|
|
|
|
Shared Vue business code lives under `frontend/src/`. Platform decisions are
|
|
exposed through `frontend/src/runtime/index.ts`.
|
|
|
|
The runtime contract currently provides:
|
|
|
|
- API base URL resolution
|
|
- Web, macOS, Windows, and Linux runtime identification
|
|
- app version, source commit, build channel, and client type metadata
|
|
- explicit capability flags
|
|
- Desktop server address configuration
|
|
- secure session storage
|
|
- file picker/save/open adapters
|
|
- desktop system notification adapters
|
|
- desktop updater adapters
|
|
|
|
Business modules must use this public runtime entry point. They must not inspect
|
|
Tauri globals or import Tauri packages directly. Native files, notifications,
|
|
secure session storage, and automatic updates must remain behind
|
|
`frontend/src/runtime/` and explicit capability flags.
|
|
|
|
## Version Change
|
|
|
|
Update every client manifest with one command:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run version:set -- 1.8.0
|
|
npm run version:check
|
|
```
|
|
|
|
This synchronizes:
|
|
|
|
- `frontend/package.json`
|
|
- `frontend/package-lock.json`
|
|
- `frontend/src-tauri/tauri.conf.json`
|
|
- `frontend/src-tauri/Cargo.toml`
|
|
- `frontend/src-tauri/Cargo.lock`
|
|
|
|
Manual edits that leave these files inconsistent fail CI.
|
|
|
|
## Promotion
|
|
|
|
1. Merge feature branches into `dev`.
|
|
2. Require the shared client/Web and macOS Desktop CI jobs to pass.
|
|
3. Promote the accepted scope from `dev` to `main`.
|
|
4. Set the release version and complete regression testing on `main`.
|
|
5. Promote `main` to `release`.
|
|
6. Create the matching `vX.Y.Z` tag on the accepted `release` commit.
|
|
7. Build both Web and Desktop artifacts from that exact tag.
|
|
|
|
Build metadata is injected by CI:
|
|
|
|
```bash
|
|
VITE_BUILD_CHANNEL=release
|
|
VITE_BUILD_COMMIT="$(git rev-parse HEAD)"
|
|
```
|
|
|
|
These values support diagnostics but do not replace the semantic version.
|
|
|
|
## Desktop Updater
|
|
|
|
Formal Desktop release builds must use Tauri updater signatures. The application
|
|
embeds the updater public key in `frontend/src-tauri/tauri.conf.json`; the
|
|
private key must live only in the organization key vault or CI secret store.
|
|
|
|
Runtime update checks derive the feed from the currently configured CTMS origin:
|
|
|
|
```text
|
|
/desktop-updates/stable/latest.json
|
|
```
|
|
|
|
Production update feeds must use HTTPS. Local update testing may use HTTP only
|
|
for `localhost`, `127.0.0.1`, or `::1`.
|
|
|
|
The release pipeline must:
|
|
|
|
1. build from the accepted release tag and commit;
|
|
2. build macOS Universal desktop artifacts;
|
|
3. sign and notarize the macOS app;
|
|
4. produce updater artifacts and `.sig` files with the updater private key;
|
|
5. generate `latest.json` and a checksum manifest;
|
|
6. upload immutable artifacts first;
|
|
7. atomically replace `latest.json` last.
|
|
|
|
For Universal macOS artifacts, `latest.json` must provide both
|
|
`darwin-aarch64` and `darwin-x86_64` entries pointing at the same Universal
|
|
update package.
|
|
|
|
## Windows Build Readiness
|
|
|
|
Second-phase Windows work is limited to CI compatibility validation. A
|
|
`windows-latest` x64 NSIS build may be produced for verification, but it is not
|
|
a formal deliverable until Windows code signing and release support are
|
|
approved.
|
|
|
|
Windows validation must cover:
|
|
|
|
- WebView2 runtime prerequisite behavior;
|
|
- user-level installer assumptions;
|
|
- Windows Credential Manager session storage;
|
|
- path handling and temporary file cleanup;
|
|
- notification and updater compilation;
|
|
- future code-signing requirements.
|
|
|
|
## Required Checks
|
|
|
|
```bash
|
|
cd frontend
|
|
npm ci
|
|
npm run version:check
|
|
npm run runtime:check
|
|
npm run type-check
|
|
npm run test:unit
|
|
npm run build
|
|
export TAURI_SIGNING_PRIVATE_KEY="$UPDATER_PRIVATE_KEY"
|
|
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="$UPDATER_PRIVATE_KEY_PASSWORD"
|
|
npm run desktop:build -- --bundles app
|
|
```
|
|
|
|
The Desktop build must run on macOS for the current first-phase target. A signed
|
|
or notarized public release additionally requires the Apple credentials defined
|
|
by the release owner. A formal second-phase desktop release also requires the
|
|
updater signing key; unsigned internal builds are not formal distributions.
|