bobluppes / bobluppes/graaf

Define a versioning/API-stability policy and fix CMakeLists version drift

Open
#324 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.