# Deploy flow: dev → staging → prod (promote the tested artifact)

Status: **design, post-launch.** The blue-green mechanism (releases + atomic
symlink swap + rollback) is built and live in `scripts/deploy.sh` (2026-06-06).
This doc is the *promotion flow* on top of it — a `deploy.sh` v3. For the launch
cutover (v1) we deploy prod directly off the same committed code staging runs;
that's good enough once. This is the durable flow for ongoing development.

## Principle
**Build once, promote the tested artifact.** Prod should only ever run the exact
release that was verified on staging — never an ad-hoc build from a dev box that
may have moved on. Mike's framing 2026-06-06: development must be able to
continue (new features/fixes) without being forced to push an untested build
straight from the dev environment to prod.

## Gaps in the current deploy.sh (to fix in v3)
1. It tars the **working tree**, so an uncommitted local change can ship.
2. A prod deploy is a **fresh rebuild**, not the staging artifact — so prod code
   isn't provably the thing staging tested.

## Target flow
1. **Dev → staging** (from the dev box): `deploy.sh --env staging`, building from
   a **committed git ref** (refuse a dirty working tree), so staging = a known sha.
2. **Test on staging.**
3. **Staging → prod = a `promote` step that runs ON pair** (not from the dev box).
   It takes the **live, tested staging release** and copies that exact tree into
   `arpartsfinder.com-releases/<same-sha>`, then swaps the prod symlink + touches
   restart. No rebuild; the dev box is never in the prod path.

This decouples prod from the dev box: the dev box only ever feeds staging, so
ongoing local development can't accidentally land an untested build on prod.

## What `promote` rewrites (everything else is copied byte-for-byte)
The release **code + venv are the tested bytes**. Only env-specific bits change:
- `public/.htaccess` → drop the basic-auth block, keep the rewrites (jump.cgi +
  static). (deploy.sh already writes the prod no-auth variant; promote produces
  the same.)
- `config.ini` symlink → repoint from `staging.arpartsfinder.com-shared` to
  `arpartsfinder.com-shared` (prod URL / secret_key / GA id).
- drop the static `public/robots.txt` (prod's Flask `/robots.txt` route serves
  it; staging's static `Disallow: /` must NOT carry to prod).

## Two decisions to lock before building it
1. **Venv identity.**
   - (a) **Pin `requirements.txt` exactly + rebuild the venv on promote** — clean,
     reproducible, no staging/prod dep drift. **Leaning this way** (pinning is good
     hygiene regardless).
   - (b) Copy the tested venv — relocatable in our case (passenger execs the venv
     python, which self-locates), fast, but slightly more fragile.
2. **Prod guard.** `--env prod` (and promote) must REQUIRE a committed sha/tag and
   refuse a dirty working tree, so prod is structurally incapable of getting an
   ad-hoc untested build.

## Changelog dating (Mike 2026-06-06)
Problem: the visitor changelog is dated at authoring/commit time today, but
visitors only ever see PROD. With a gap between the staging release and the prod
promote (could be a day+), an entry would show the date it hit *staging*, not
the date it went live for users.

Decision: **date the changelog at PROD release, not at authoring.** Adopt an
undated **Unreleased** block — author entries there (content only, no date); the
prod promote step **stamps that block with the prod go-live date** and folds it
into the dated history. Staging renders it as "Unreleased". This is the single
place staging and prod artifacts intentionally differ (the date is a prod fact,
not code; the bullets are identical). Requires: the changelog renderer handles an
undated "Unreleased" group, and the promote step does the stamp. Aligns with the
existing "same-day fixes fold in" convention — just deferred to the prod date.

## Shape of the work
- `deploy.sh --env staging` builds from `git archive <ref>` (committed code only).
- `deploy.sh --promote [--from staging]` (runs the copy+adjust+swap on pair).
- Dirty-tree / require-ref guards on the prod path.
- Pin `requirements.txt`.

Related: blue-green mechanism in `scripts/deploy.sh`; `cutover-checklist.md`;
memories [[site-ng-deploy-script-shape]] (single-file config model),
[[deploy-tar-exclude-precision]].
