# Releasing the docs site

How the docs portal (docs.djangoplay.org) is versioned and released. This is
the same process the djangoplay-site repository uses.

**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.

| Version | What it versions | Source of truth | Git tag | Shown on |
| --- | --- | --- | --- | --- |
| **Docs site** (e.g. `3.0.0`) | The portal itself: code, design, build | `package.json` → `version` | `v3.0.0` | Footer badge (`v3.0.0`; build commit on hover) and `/version.json` |
| **Documented project** (e.g. gitaiflow `1.1`) | One product's documentation | `projects/<slug>/project.json` → `versions` | `gitaiflow/v1.1` | The **Version** picker in that project's sidebar |

Project versions are covered in [VERSIONING.md](./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`:

  ```bash
  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](https://semver.org/):

| Bump | When | Example |
| --- | --- | --- |
| **patch** | Fixes to the portal: styling, copy, a bug | `3.0.0 → 3.0.1` |
| **minor** | New portal features or pages: a new component, a new project added to the hub | `3.0.1 → 3.1.0` |
| **major** | Breaking changes to URLs or structure | `3.1.0 → 4.0.0` |

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

```bash
# 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

```bash
# 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.

| Command or variable | Effect |
| --- | --- |
| `npm run build` | Builds the site and prints the warnings once |
| `npm run check-content` | Checks content only (no bundling) and prints the same warnings. Fast enough for a pre-commit hook |
| `npm run docs:check` | Checks every doc's header and structure against [DOCS_STANDARD.md](./DOCS_STANDARD.md); `--report` writes `docs-report.md` |
| `npm run check-content -- --strict` or `DOCS_STRICT=1` | Any warning fails the build or the check (for CI) |
| `DOCS_VERBOSE=1` | List every warning, not just the first few of each kind |