Releasing the docs site

Audience: anyone who cuts a release of this repository.

#1. Two kinds of version

This repository has two unrelated kinds of version. Don't mix them up.

Project versions are covered in VERSIONING.md. The rest of this page is about the docs site version.

The tag names never clash: site tags are vX.Y.Z, and project tags always start with the project's slug (<slug>/vX.Y).

#2. How the site version reaches the page

You never type a version into source code.

• At build time build/build-info.ts reads the version from package.json, and the short commit SHA from Cloudflare Workers Builds, GitLab CI, GitHub Actions or the local git checkout.

• vite.config.ts injects both as __APP_VERSION__ and __APP_COMMIT__. Vite's define covers the browser bundle and the SSR bundle that prerenders the static HTML, so both always agree.

• App code reads them through src/config/site.ts (appVersion, appCommit).

• The build also writes /version.json:

  curl -s https://docs.djangoplay.org/version.json
  # { "name": "djangoplay-docs", "version": "3.0.0", "commit": "a1b2c3d" }
  

A missing commit (for example, a build from a zip with no git) never fails the build. The footer just shows the version without a commit.

#3. When to bump

The site follows Semantic Versioning:

Editing or adding Markdown docs doesn't need a site version bump on its own. The commit SHA already tells two builds apart. Bump when you release something you'd write in CHANGELOG.md.

#4. Releasing a new site version

# 1. Record the release: move the "## [Unreleased]" notes in CHANGELOG.md
#    under a new "## [3.0.1] - YYYY-MM-DD" heading, then regenerate the
#    release notes from that entry:
gitaiflow --release-notes

# 2. Bump the version (updates package.json and package-lock.json, no tag yet)
npm version patch --no-git-tag-version     # or minor / major

# 3. Commit, open an MR, merge to main. Cloudflare deploys it.

# 4. Tag the merge commit on main and push the tag
#    (a plain `git push` does not push tags)
git tag -a v3.0.1 -m "djangoplay-docs v3.0.1"
git push origin v3.0.1

The CHANGELOG.md version, the package.json version and the git tag must always match.

#5. Checking a deployment

# which version and commit is live?
curl -s https://docs.djangoplay.org/version.json

# does it match the tag?
git rev-parse --short v3.0.1

In the browser, hover the version badge in the footer to see the build commit.

#6. Build warnings

Every build prints a single grouped list of non-fatal problems (versioning fallbacks, missing frontmatter, missing dates, broken links inside old snapshots). Errors still fail the build as before.