Test/docs/adr/0012-use-stadium-themed-semantic-versioning.md

0012. Use Stadium-Themed Semantic Versioning

Date: 2026-04-02

Status

Accepted

Context

The project follows Semantic Versioning (MAJOR.MINOR.PATCH) for release numbers. Purely numeric version strings are accurate but forgettable — contributors and users rarely remember whether "2.1.0" came before or after "2.0.3" without consulting the changelog.

The project is football-themed (it manages football player data), and is part of a cross-language comparison set. A naming convention that reflects the project's domain makes releases memorable and reinforces the project's identity.

Several well-known projects use codename conventions: Ubuntu (alphabetical adjective-animal pairs), Android (alphabetical desserts until Android 10), macOS (California landmarks). The pattern is established and understood.

Decision

We will append a football stadium codename to every release tag, following the format vMAJOR.MINOR.PATCH-stadium (e.g., v2.1.0-dusseldorf). Stadium names are drawn from a fixed, alphabetically ordered list of venues that hosted FIFA World Cup matches, documented in CHANGELOG.md. Names are assigned sequentially A→Z; the next release always uses the next unused letter. The tag format is enforced by the CD pipeline, which validates the stadium name before publishing.

Consequences

Positive

• Release names are memorable: "the dusseldorf release" is easier to recall and discuss than "2.1.0".
• Alphabetical ordering provides an implicit sequence — contributors can determine release order from the name alone without consulting version numbers.
• The convention is consistent and deterministic: there is no ambiguity about which name comes next.
• Reinforces the football domain theme throughout the project's lifecycle.

Negative

• The convention is non-standard and may confuse first-time contributors who expect plain semantic version tags.
• The stadium list is finite (26 letters). If the project ever reaches 26 major releases, the list must be extended or the convention revisited.
• The CD pipeline validation adds a small amount of CI complexity to enforce the format.

Neutral

• The stadium list is published in CHANGELOG.md under "Stadium Release Names" for reference. The current position in the sequence is always the last released tag — the next unused letter determines the next stadium name.