# 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

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 remain disabled until their
second-phase adapters are implemented and reviewed.

## 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.

## 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
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; an unsigned internal build is not a formal distribution.