Versioning

CSDB repos release independently. There are no coordinated multi-repo releases by default.

Each versioned repo owns its own make release version=x.y.z command. Running a release target in one repo only versions that repo, pushes that repo's tag, and creates that repo's GitHub Release.

Versioned Repositories

Repository	Version source	Release artifact
specification	VERSION	GitHub Release
csdb-javascript	package.json	GitHub Release + npm package
csdb-python	pyproject.toml	GitHub Release + PyPI package
documentation	package.json	GitHub Release + built docs verification
server-typescript	package.json	GitHub Release + GHCR container image
api-typescript	package.json	GitHub Release + npm package

The website and main csdb project-overview repos are not versioned packages right now. They can deploy or change independently without semantic releases.

Releasing One Repo

From the repo you want to release:

make release version=1.1.1

The standard release target:

1. validates that version is full semver (x.y.z)
2. requires a clean working tree
3. verifies major release branch rules for x.0.0
4. updates that repo's version source
5. runs repo-local checks/builds
6. commits the version bump
7. creates and pushes tag v<version>
8. pushes the current branch
9. creates a GitHub Release for that tag

Published GitHub Releases then trigger repo-local release workflows. Package repos publish to their package registry from those workflows.

Major Release Branches

A major release is any version whose minor and patch are both zero:

1.0.0
2.0.0
3.0.0

Major releases must be cut from a matching major branch:

Version	Required branch
1.0.0	v1
2.0.0	v2
3.0.0	v3

For example:

git switch v1
make release version=1.0.0

Patch and minor releases do not create or require new major branches. They can be released from the branch appropriate for that repo's maintenance flow.

Branch Utilities

The documentation repo keeps two helper commands for branch visibility across the local checkout and the GitHub remotes:

make check-local-version
make check-remote-version

Both commands list every branch they find for each tracked repo and sort the table by branch:

Repo             Path                Branch
----             ----                ------
docs             .                   main
specification    ../specification    main
csdb-javascript  ../csdb-javascript  v1
csdb-python      ../csdb-python      v1

check-local-version reads local repositories from paths configured in the Makefile. check-remote-version reads remote branches from GitHub URLs configured in the Makefile. These commands do not create branches, publish releases, or modify files.

Documentation Branches

Documentation content is versioned by the specification/API major version. For example, the v1 documentation branch should pin compatible v1 content and the main branch should represent the latest active docs.

The version dropdown reads versions.json from the live docs site:

{
  "versions": [
    { "label": "main", "href": "https://docs.csvdatabase.net/" },
    { "label": "v1", "href": "https://v1.docs.csvdatabase.net/" }
  ]
}

Hosting Versioned Docs

Deploy each docs branch to Cloudflare Pages:

main -> docs.csvdatabase.net
v1   -> v1.docs.csvdatabase.net
v2   -> v2.docs.csvdatabase.net

Use the Cloudflare helper to register version domains:

make cloudflare domain VERSION=v1

Required environment variables:

CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...
CLOUDFLARE_ZONE_ID=...
CLOUDFLARE_PAGES_PROJECT=...
DOCS_DOMAIN=docs.csvdatabase.net