Canonical release workflow

KLookup has a single CI/CD workflow at .github/workflows/ci.yml. It validates PRs, main, and monthly scheduled checks, and publishes developer documentation from main.

Release readiness: Issue #73 tracks outstanding public-release checks, including maintainer sign-off, secrets/history and asset provenance audits, production script credentials, and live Plasma verification. Do not initiate a public release until these checks are approved. Merely enabling a release mode is not release approval.

Manual actions

Open Actions → CI/CD → Run workflow, select branch main, and choose a mode:

Mode Effect
build Validate sources, docs, licensing, normal tests and ASan/UBSan; no tag or software release
monthly-maintenance Run the same verification manually (also performed on the monthly schedule)
release-patch Prepare and publish the next patch version
release-minor Prepare and publish the next minor version
release-major Prepare and publish the next major version
release-test Prepare the next test prerelease
release-rc Prepare the next release candidate
release-alpha Prepare the next alpha prerelease
publish-tag Revalidate and publish an existing v* tag, not a new version

Release modes use arran4/git-tag-inc for version arithmetic. The optional release_version_override applies to release-* modes only. It selects an explicit vMAJOR.MINOR.PATCH (optionally with a prerelease suffix) rather than calculating a version. The workflow never moves a pre-existing tag. To recover a failed publication, dispatch publish-tag from the intended tag, rather than rerunning auto-increment and potentially selecting a different version.

Versioning mechanism

Git is KLookup's version authority; no manually maintained root VERSION file or hardcoded release baseline exists.

  1. An explicit build/packager override: cmake -DKLOOKUP_VERSION=x.y.z, for an externally known version. Tag CI passes its exact Git ref and Gentoo ebuilds may pass -DKLOOKUP_VERSION=${PV} in src_configure(). The override is validated as a semantic version.
  2. Git checkouts use git describe --tags --match 'v[0-9]*' --abbrev=12 HEAD. Exact tags report their version (including prerelease suffixes); development commits report the nearest release tag, distance and commit hash. The build must have reachable release tags for this description, so CI fetches complete history.
  3. Git source archives use Git's export-subst metadata in cmake/KLookupArchiveVersion.cmake, including the Git description and commit hash. Tagged GitHub archives do not need a Git checkout or a manually maintained version. The generated release asset stamps the exact selected Git tag in this same metadata file, not in a tracked VERSION file.
  4. With no reachable tag, a known Git revision reports 0.0.0-dev+g<hash>. A copied source tree with neither Git metadata nor an explicit version reports 0.0.0-unknown rather than falsely claiming a previous release. Packagers should use a tagged archive or supply the known package version.

The build exposes PROJECT_VERSION (semantic numerical format) and KLOOKUP_VERSION_STRING (full version identifier). KAboutData and QCoreApplication::setApplicationVersion derive directly from KLOOKUP_VERSION_STRING. Release workflows verify candidate binaries to ensure installed packages and GitHub release tags agree without manual UI source edits.

Release gates and publication

  1. The workflow runs normal and sanitizer CTest, REUSE, Actionlint and documentation validation.
  2. The normal CMake build is installed into a staging prefix and archived as klookup-linux-amd64.tar.gz with a checksum file. This is a Linux installation-layout archive requiring installed Qt6/KF6 dependencies, not an AppImage or standalone portable binary.
  3. A separate job downloads those exact artifacts, verifies their checksum, and inspects the staged executables, provider assets and ELF format.
  4. A release-quality gate requires the complete validation aggregate and artifact-smoke job to succeed.
  5. For release-* modes, a serialized job verifies the validated commit is still origin/main, calculates the tag, checks for an existing exact-SHA tag, rechecks main immediately before pushing a new immutable tag, then dispatches the same workflow against that tag.
  6. On tag-context validation, a single publisher verifies the tag and ancestry, then creates the GitHub Release or resumes an existing exact-target release by uploading the validated artifacts. Prerelease tags are marked as prereleases.

GitHub token access defaults to read-only. Only tag preparation has contents:write / actions:write, and the publisher has contents:write. Release actions must be permitted by repository GitHub Actions settings. Publication does not use a second release action, a release-event listener, or an independent rebuild.

Recovery and limitations

  • A failure before tagging does not create a release. Review the failing test or build instead of manually tagging the old commit.
  • A failure after the tag exists is recovered from that exact tag with publish-tag.
  • An existing release that targets a different commit is rejected; the workflow never silently moves or replaces release identity.
  • External v* tag pushes enter the same validation/publisher path, provided the tagged commit is on main.
  • The packaged archives are not an endorsement of installation on arbitrary Linux distributions. Release verification still requires a live supported KDE Plasma installation.

The workflow supports only Linux amd64 release candidates. Other operating systems and packaging formats need implementation and testing before being added.