bobluppes / bobluppes/graaf

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

Aperta
#324 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
C++
Stelle
413
Fork
67
Merge medio
7h 24m
PR unite (30g)
53

Descrizione

## 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).

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
cmake, cpp
Ambito
build-system, documentation, release
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Attiva
Chiarezza
Specificata chiaramente
Idoneità per principianti
65/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.