# Versioning Policy

## Source Of Truth

- Canonical version: root `package.json` field `version`
- Tag format: `vX.Y.Z`

Tag validation is enforced in CI:

- `.gitea/scripts/validate-tag-version.sh`

## SemVer Strategy

- `major`: breaking API/behavior changes
- `minor`: backward-compatible features
- `patch`: backward-compatible fixes

## Build Metadata Policy

Use git metadata in runtime display format:

- `<version>+sha.<short>`

Example:

- `0.1.0+sha.a1b2c3d`

## Footer Display Plan (Admin + Web)

Planned runtime footer fields:

- app name
- version from root `package.json`
- commit hash (short)
- environment (`dev|staging|production`)

Implementation note:

- inject values at build/deploy time through env vars
- render in shared footer components

## CI Version Injection

Release/deploy workflows pass release tag and commit metadata:

- `.gitea/workflows/release.yml`
- `.gitea/workflows/deploy.yml`

Required inputs:

- release tag (`vX.Y.Z`)
- image tag for deployment

## Validation Strategy

CI validations:

- tag equals `v${package.json.version}`
- required checks pass before release builds

Runtime validations (planned):

- smoke tests assert footer version/hash format
- environment-specific deployment checks assert expected image tag

## Changelog and Release Publication

- changelog generation command:
  - `bun run changelog:release`
- release workflow generates changelog on tag pipeline
- release notes publication remains a dedicated step in CI workflow.