bitvid/docs/deployment-notes.md

Deployment Notes

Design system rollout

• Status: The design system styling is always active. The former FEATURE_DESIGN_SYSTEM runtime flag has been removed, so there is no rollback toggle during deployment.
• Template contract: Every layout, view, and partial must keep data-ds on its root element. The entrypoint stamps data-ds="new" during bootstrap so controllers inherit the correct primitives.
• Controllers: UI controllers still receive a designSystem context, but context.isNew() now always returns true. Use the context for consistency, but do not branch on legacy styling paths.

Asset freshness and cache invalidation

• Static CSS/JS asset freshness is now driven by build-time manifest rewriting (dist/asset-manifest.json) instead of runtime ASSET_VERSION query-string mutation.
• Keep source HTML entry points (index.html, embed.html) pointing at logical asset paths (for example, js/index.js and css/tailwind.generated.css). The build pipeline rewrites those references to content-hashed filenames in dist/.
• Deploy pipelines should always purge HTML entrypoints (/ + /index.html and /embed.html) at the edge after publish so clients do not keep serving stale source shells.
• App routing query parameters (such as ?v= for video pointers) are unchanged and remain part of runtime URL behavior.

Release channels → Vercel projects (promotion + on-demand deploy)

The three release branches each map to a separate Vercel project under the pr0m3th3ans-projects team:

Branch	Vercel project	Live URL
unstable	bitvid-unstable	unstable.bitvid.network
beta	bitvid-beta	bitvid-beta.vercel.app
main	bitvid	bitvid.network (prod)

The repo's local .vercel/project.json is normally linked to bitvid-unstable so day-to-day vercel deploy --prod targets the unstable site.

vercel.json knobs

• installCommand: "npm install" is pinned because both package-lock.json and pnpm-lock.yaml exist; without the pin Vercel auto-selects pnpm and the build fails on the unstable/beta projects.
• git.deploymentEnabled.unstable: false disables auto-deploy for a branch named unstable. It only affects that branch key, so it's harmless on the beta/main projects (they deploy beta/main). The bitvid-beta/bitvid projects ARE git-connected, so a push to beta/main also auto-triggers a build — explicit CLI deploys (below) just make the result deterministic.

Promotion (unstable → beta → main)

unstable is the integration branch. main is usually a clean ancestor (fast-forward). beta can carry an extra superseded commit (e.g. an old vercel.json pin), so prefer a merge that takes unstable's tree:

# beta: merge unstable, preferring unstable on conflict; verify trees match
git checkout beta && git reset --hard origin/beta
git merge origin/unstable -X theirs --no-edit -m "Promote unstable → beta: <summary>"
git diff --quiet origin/unstable HEAD && echo "beta tree == unstable"   # expect 0
git push origin beta

# main: fast-forward to unstable
git checkout main && git reset --hard origin/main
git merge --ff-only origin/unstable
git push origin main

Build/deploy each project (on-demand)

# beta
vercel link --yes --project bitvid-beta && vercel deploy --prod --yes
# production
vercel link --yes --project bitvid && vercel deploy --prod --yes   # aliases to bitvid.network
# restore the day-to-day link
vercel link --yes --project bitvid-unstable

Verify

The footer version marker (v: <8hex> • <date>) is content-hash based; all three projects build from the same source in the same Vercel env, so the markers should match each other after a promotion. Verify per domain and confirm a known new module is served, e.g.:

for host in unstable.bitvid.network bitvid-beta.vercel.app bitvid.network; do
  echo -n "$host : "; curl -s "https://$host/index.html?cb=$(date +%s)" \
    | grep -oE 'v: [0-9a-f]{8} • [0-9-]+' | head -1
done

Caveat: promoting a large batch straight to main skips the beta soak. Do it only deliberately; otherwise let changes soak on beta first. Rollback = redeploy the previous bitvid production deployment (vercel rollback or redeploy by URL).