#documentation #ci-cd #github-actions

# CI/CD Guide

This guide defines the CI/CD behavior for Card Collection Manager 3. For the complete versioning policy, including prefix semantics and tag rules, see [Versioning Guide](versioning.md). For how the Windows installer artifact is produced and configured, see [Windows Installer Guide](windows-installer.md).

**Quick Setup:** protect `master` with the required check `Require semver prefix in PR title`, then keep release PR titles aligned with the accepted prefixes.

## Workflow Map

The repository uses GitHub Actions workflows split by branch intent, with one orchestrator per branch intent:

- `feature-ci.yml`: single workflow run for non-`master` pushes; orchestrates Linux and Windows feature builds.
- `feature-linux.yml`: reusable Linux build/test/package workflow invoked by `feature-ci.yml`.
- `feature-windows.yml`: reusable Windows build/test/package workflow invoked by `feature-ci.yml`.
- `master-pr-title-guard.yml`: validate PR title prefixes for PRs targeting `master`.
- `master-ci.yml`: single workflow run on merged PRs to `master`; computes semver, invokes Windows reusable build, then tags/publishes release assets.
- `master-windows.yml`: reusable Windows build/test/package workflow invoked by `master-ci.yml`.

### SonarQube Cloud (coverage quality gate)

Both `feature-ci.yml` and `master-ci.yml` include a Linux job that configures with GCC coverage flags, builds, runs `ctest`, generates `build/sonarqube-coverage.xml` via `gcovr`, and runs the SonarCloud scan. **`sonar.coverage.exclusions`** omit `ui_wx/` and `app/` from the coverage denominator because only `ccm_core` is exercised by automated tests. The scan also sets **`sonar.cpd.exclusions`** for the repeated per-game wx scaffolding files (`*GameView.cpp`, `*CardEditDialog.cpp`, `*SelectedCardPanel.cpp`) so intentional parallel UI implementations do not drive the duplication gate. See [Testing Guide And Test Code Of Conduct](testing-and-test-code-of-conduct.md).

## Version Flow

Feature branches and `master` use different version modes because they solve different problems: feature builds need traceability to a commit, while `master` builds need stable semantic releases.

### Feature Branch Builds

On pushes to non-`master` branches, `feature-ci.yml` fans out to Linux and Windows reusable workflows. Each platform workflow computes a version string in the format `<branch-name>-<short-sha>` via `scripts/compute_feature_version.sh` (for example `feature-dark-mode-a1b2c3d`).

That version is used in two places:

- artifact file names
- app embedded version via `-DCCM_APP_VERSION=...`

### Master Releases

When a PR is merged into `master`, `master-ci.yml` computes the next semantic version from the latest semver tag and the PR title prefix using `scripts/compute_master_semver.sh`.

Accepted prefix mapping:

- `major...` -> major bump
- `minor...` -> minor bump
- `fix...` -> patch bump
- `patch...` -> patch bump
- `path...` -> patch bump (accepted alias in current setup)

The resulting version is embedded in the app (`CCM_APP_VERSION`), used in artifact names, and tagged as `v<version>`.

## Master Merge Guard

PRs targeting `master` must start with one of the accepted prefixes:

- `major`
- `minor`
- `fix`
- `patch`
- `path`

If a title does not match, `master-pr-title-guard.yml` fails and the PR should not be merged.

## Artifact Naming

Feature workflow artifacts (produced by jobs inside `feature-ci.yml`):

- Windows: `ccm3-windows-<version>.zip`, `ccm3-windows-installer-<version>`
- Linux: `ccm3-linux-<version>.zip`

Master release artifacts (`master-ci.yml`, built via `master-windows.yml`):

- `ccm3-windows-<semver>.zip`
- `ccm3-windows-installer-<semver>.exe`

## Release Procedure

Follow this flow for every release:

1. Open a PR to `master`.
2. Use a valid semver prefix in the PR title (`major:`, `minor:`, `fix:`, `patch:`, or `path:`).
3. Wait for all required checks to pass.
4. Merge the PR.
5. Wait for `master-ci.yml` to complete semver computation, Windows build/test, tag creation, and release publishing.
6. Verify the `vX.Y.Z` tag and release assets in GitHub.

## Local Build Version Behavior

Outside CI, the app version defaults to `${PROJECT_VERSION} (localbuild)` through `CCM_APP_VERSION` in the top-level `CMakeLists.txt`. This keeps local binaries easy to distinguish from CI and release outputs.

## Troubleshooting

- **`msys2: command not found` in workflow logs:** ensure the MSYS2 setup step runs before jobs that use `shell: msys2 {0}`.
- **`Permission denied` while linking `ccm3.exe`:** the app is still running; close it and rebuild.
- **No release after merge:** verify the PR merged into `master` and used a valid prefix, then inspect `master-ci.yml` logs for version/tag/release failures.