Define a versioning/API-stability policy and fix CMakeLists version drift
- Dominant language
- C++
- Stars
- 413
- Forks
- 67
- Avg merge
- 7h 24m
- Merged PRs (30d)
- 53
Description
## Summary
There is no documented versioning or API-stability policy, and the version declared in [CMakeLists.txt](../blob/main/CMakeLists.txt) has drifted from the actual released version.
## Current state
- `CMakeLists.txt` declares `project(Graaf VERSION 0.1.0 ...)`, but the most recent published tag is `v1.1.1` (with `v1.1.0`, `v1.0.0`, `v0.2.0-beta`, `v0.1.0-beta` before it). The in-tree project version has not tracked releases for at least three minor/major versions.
- Nothing in the README, docs, or CONTRIBUTING.md states what "breaking change" means for this project, what the criteria are for a major vs. minor vs. patch bump, or what deprecation process (if any) precedes a breaking change. The `.github/ISSUE_TEMPLATE` set includes a `breaking-change` label (used e.g. on #238), so the concept exists informally, but it isn't written down anywhere.
- The generated `graaf.pc` pkg-config file and any future CMake package config (see the related `find_package` issue) will both need a correct, meaningful version to support version-range dependency resolution (`find_package(Graaf 1.2 REQUIRED)`, vcpkg/Conan version pinning, etc.) — this doesn't work correctly while `CMakeLists.txt` reports `0.1.0`.
## Why this matters
Teams that take a dependency on a library want to know, before upgrading, whether a new release can break their build/behavior, and want their build tooling to be able to express and enforce version constraints. A stale, out-of-sync version number silently defeats both: any tool that queries the package version (CMake, pkg-config, vcpkg, Conan) currently reports `0.1.0` regardless of which tag is actually checked out, and there's no written policy on what a version bump means, making it hard to assess upgrade risk.
## Suggested resolution
- Set `CMakeLists.txt`'s `project(VERSION ...)` to match the current release, and update it as part of the release process (or derive it automatically from the git tag, e.g. via a small CMake script or `git describe`).
- Adopt and document a semantic-versioning policy (what constitutes major/minor/patch), including how deprecations are announced and how long deprecated APIs are kept before removal.
- Reference this policy from CONTRIBUTING.md and the release workflow.
## Acceptance criteria
- [ ] `CMakeLists.txt` version matches the latest release tag, and stays in sync going forward (documented or automated).
- [ ] A versioning/API-stability policy is documented (e.g. `VERSIONING.md` or a section in CONTRIBUTING.md).
Contributor guide
Research direction
The main file to edit is CMakeLists.txt at the root, which currently declares version 0.1.0. Check the git tags (v1.1.1 is latest) to understand the version history. You'll need to update the CMake project version and then draft a versioning policy document, referencing existing practices like the 'breaking-change' label used in issue #238. Look at CONTRIBUTING.md and the .github/ISSUE_TEMPLATE to see where to link the new policy.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cmake, cpp
- Domain
- build-system, documentation, release
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 65/100