Skip to content

docs/versions/ — release versioning

This directory is a thin shell around the git-tag-based versioning model. The working copy of the documentation lives at the top level of docs/ and tracks master; releases are pinned via annotated git tags (v1.0, v1.1, …) rather than per-version snapshot directories.

Why no snapshot directories? A previous design copied docs/ into versions/v<X.Y>/ via freeze.sh. That approach was never actually executed (the scaffolds were empty and freeze.sh never ran in anger). For a docs portal already living in git, an annotated tag gives the same immutability with zero duplication and full GitHub-side tag browsing. The snapshot directories and freeze.sh were removed in 2026-05.

How to cite a specific release externally

When you cite a doc in an external ticket or email, link via the tag path on GitHub:

https://github.com/evo-spin/ebit-docs/blob/v1.0/business/value-proposition.md

The blob/v1.0/... URL is permanent — it won't shift as the working copy on master evolves.

Versioning model

Three things have version numbers in this codebase. They are independent:

Version What it tags Source of truth
API version The OpenAPI surface (info.version in the live Swagger spec). docs/api/changelog.md, driven by Nest buildSwagger(...) calls
Doc version (git tags v1.0, v1.1, …) The state of the documentation portal — content, structure, conventions. docs/versions/changelog.md — human-readable log of doc releases
Product / release The deployable iGaming platform. Internal release notes (out of scope for this portal)

Doc version v1.0 is the initial baseline of the portal — the first release where the full three-track structure (business / delivery / engineering) plus the cross-cutting reference set is in place. Future doc releases bump independently; bumping the API version does not automatically bump the doc version.

Release cadence

  • Patch (v1.0.0 → v1.0.1) — typo / clarification / link fixes that don't change the structure or facts. Edit working copy in place; mention in changelog.md. No new tag required for patches.
  • Minor (v1.0 → v1.1) — new sections, new cross-cutting docs, additional ADRs, structural refactors that don't break external links. Tagged: git tag v1.1 && git push origin v1.1.
  • Major (v1.x → v2.0) — breaking restructure: top-level directory renames, deletion of customer-cited paths, terminology changes. Tagged + a written migration note in changelog.md.

There is no fixed cadence — a doc release happens when one of the trigger conditions above is met. Typically expect 1-2 minor releases per quarter.

Release process (short form)

When ready to cut a doc release vX.Y:

  1. Working copy is fully merged on master and CI is green (docs/ci/ — link checker, {{TBD}} scanner, terminology lint).
  2. Append a release entry to changelog.md — date, headline changes, any migration notes for downstream readers.
  3. git tag -a vX.Y -m "Doc release vX.Y" and git push origin vX.Y.
  4. (Optional) cross-link from docs/api/changelog.md if the doc release coincides with a notable API release.

Authoring workflow (when to update working copy vs branch, how to draft {{TBD}} blocks, customer-review gates) is in CONTRIBUTING.md.

Files in this directory

File What's inside
README.md This file — versioning model, release cadence, release process.
changelog.md Doc-system changelog (human-readable).
CONTRIBUTING.md Authoring workflow — when to update vs branch, TBD/draft/final markers, customer-review gate, doc CI integration.