Remove auto-tag, document manual tagging

- test

- cover

- pages

- tag

- upload

- release

    when: manual

    allow_failure: true

# Auto-tag when version in CMakeLists.txt is newer than latest git tag.

# Uses git push to create the tag, then the API to trigger a pipeline for it

# (git push from CI_JOB_TOKEN doesn't auto-trigger tag pipelines).

auto-tag:

  stage: tag

  script:

  - dnf install -y git curl

  - VERSION=$(sed -n 's/.*VERSION \([0-9]*\.[0-9]*\.[0-9]*\).*/\1/p' CMakeLists.txt)

  - |

    if git ls-remote --tags origin "refs/tags/v${VERSION}" | grep -q .; then

      echo "Tag v${VERSION} already exists, skipping"

    else

      echo "Creating tag v${VERSION}"

      git tag "v${VERSION}"

      git push "https://gitlab-ci-token:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git" "v${VERSION}"

      echo "Triggering pipeline for v${VERSION}"

      curl -s --fail --request POST \

        --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \

        --form "ref=v${VERSION}" \

        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/trigger/pipeline"

    fi

  rules:

  - if: $CI_COMMIT_TAG

    when: never

  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

variables:

  # Package version can only contain numbers (0-9), and dots (.).

  # Must be in the format of X.Y.Z, i.e. should match /\A\d+\.\d+\.\d+\z/ regular expresion.

## Versioning and Releases

The version is defined in the top-level `CMakeLists.txt` (`project(cppduals VERSION X.Y.Z ...)`). GitLab CI (`.gitlab-ci.yml`) handles tagging, packaging, and release creation automatically:

The version is defined in the top-level `CMakeLists.txt` (`project(cppduals VERSION X.Y.Z ...)`). GitLab CI (`.gitlab-ci.yml`) handles packaging and release creation automatically when a tag is pushed:

- **auto-tag** stage: when a commit lands on master, reads the version from `CMakeLists.txt` and creates a `vX.Y.Z` tag if it doesn't already exist

- **upload** stage: on tag push, creates a header-only tarball and publishes it to the GitLab package registry

- **release** stage: on tag push, creates a GitLab release linked to the package

- **upload** stage: creates a header-only tarball and publishes it to the GitLab package registry

- **release** stage: creates a GitLab release linked to the package

To cut a new release, just bump the version in `CMakeLists.txt` and merge to master — CI does the rest:

To cut a new release:

```bash

# 1. Update the VERSION in CMakeLists.txt

#    project(cppduals VERSION 0.7.1 ...)

# 2. Commit and merge to master — CI auto-tags and releases

git commit -am "Bump version to 0.7.1"

git push origin master

# 2. Commit the version bump and merge to master

# 3. Tag and push — CI does the rest

git tag v0.7.1

git push origin v0.7.1

```

**IMPORTANT:** After merging an MR that bumps the version, you must manually push a tag matching `vX.Y.Z` to trigger the release pipeline. The tag name must match the version in `CMakeLists.txt`.

## Code Conventions

- Comment WHY, not WHAT.