major: initial release

* initial development * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * pipeline * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * ci/cd * pokemon * pokemon * pokemon * pokemon * pokemon * pokemon * improvements * improvements * ci/cd * ci/cd * improvements * improvements * improvements * improvements * improvements * improvements * improvements * improvements * improvements --------- Co-authored-by: sdine <sdine@sdine.com>
2026-08-29 00:01:07 +00:00 · 2026-05-09 11:05:47 +02:00
parent 13262fa015
commit 55ace147bc
149 changed files with 12611 additions and 0 deletions
@@ -0,0 +1,89 @@
+#documentation #versioning #releases
+
+# Versioning Guide
+
+This guide defines how Card Collection Manager 3 assigns versions in CI and release flows. For workflow wiring and release execution details, see [CI/CD Guide](ci-cd-guide.md).
+
+**Quick Setup:** choose a valid PR title prefix before opening a `master` PR because the prefix determines the release bump.
+
+## Versioning Model
+
+The project uses two versioning modes:
+
+- feature-build versioning for non-`master` branches
+- semantic versioning for merged PRs into `master`
+
+## Feature-Build Versioning
+
+Non-`master` pushes use `<branch-name>-<short-sha>` (for example `feature-dark-theme-a1b2c3d` or `fix-sort-order-f91d2ab`).
+
+Rules:
+
+- branch names are sanitized and lowercased
+- commit SHA is shortened to 7 characters
+- computation runs in `scripts/compute_feature_version.sh`
+
+Usage:
+
+- artifact names
+- app embedded version (`CCM_APP_VERSION`, visible in `Help -> About`)
+
+## Master Semantic Versioning
+
+Merged PRs into `master` use semantic versions in `MAJOR.MINOR.PATCH` format (for example `1.4.2`).
+
+CI computes the next version from the latest semver tag and the PR title prefix:
+
+- `major...` -> bump `MAJOR`, reset `MINOR` and `PATCH` to `0`
+- `minor...` -> bump `MINOR`, reset `PATCH` to `0`
+- `fix...` -> bump `PATCH`
+- `patch...` -> bump `PATCH`
+- `path...` -> bump `PATCH` (accepted alias in current setup)
+
+Computation runs in `scripts/compute_master_semver.sh`.
+
+## Validation Rules
+
+If the PR title prefix is not accepted, two controls fail by design:
+
+- PR title guard check for `master` PRs
+- semantic-version script validation
+
+This enforcement keeps release bumps deterministic and reviewable.
+
+## Tag Format
+
+Master releases create git tags in this format:
+
+- `v<semantic-version>`
+
+Examples:
+
+- `v1.0.0`
+- `v2.3.7`
+
+## Embedded App Version
+
+The app embeds a build-time version string through CMake variable `CCM_APP_VERSION`.
+
+CI behavior:
+
+- feature workflows set it to `<branch>-<sha>`
+- master release workflow sets it to semantic version
+
+Local/manual behavior:
+
+- default is `${PROJECT_VERSION} (localbuild)` unless overridden
+
+This default makes local binaries easy to distinguish from CI and release outputs.
+
+## PR Title Conventions
+
+Use explicit prefixes in this shape:
+
+- `major: <summary>`
+- `minor: <summary>`
+- `fix: <summary>`
+- `patch: <summary>`
+
+Example: `minor: add custom themed confirmation dialogs`.