Ship a change, step by step

The flow at a glance

The steps in order. If a test fails, loop back and fix it; never push past a red run.

1 · Version and change log

The number on the badge in the bottom-right corner of the site comes from the top entry of CHANGELOG in app/index.html and nowhere else; no other file needs editing.

1. Use the date as the version (YYYY.MM.DD)

   Same shape as the existing ones, such as 2026.10.17. Use the real release date.

   # Today's date = the version
   date +%Y.%m.%d                          # bash / Git Bash
   Get-Date -Format yyyy.MM.dd             # PowerShell
   
   # See the top entry of CHANGELOG
   grep -n "version: '" app/index.html | head -3                          # bash
   Select-String "version: '" app/index.html | Select-Object -First 3     # PowerShell

2. Add a new entry at the top of CHANGELOG

   The new entry goes at the top; the badge reads the first one. Write each item as a short English sentence (the UI is English), starting with an area such as Docs:, Tests: or Sign-in page:.

   const CHANGELOG = [
     { version: '2026.10.18', changes: [
       'Docs: added the user journey page (Thai and English)',
       'Docs: added the release guide (Thai and English)',
     ] },
     { version: '2026.10.17', changes: [ /* ... */ ] },
   ];

3. Releasing twice on the same day

   A version is a date, so it cannot repeat. Add items to that day's entry instead of creating a new one.

4. Check it in the app

   Run npm start and open http://localhost:3000. The bottom-right badge must show the new number. Press and hold for about 0.6 seconds (or focus it and press Enter/Space) to open the change log and confirm the new entry is on top.

2 · Run the tests before pushing

CI repeats these anyway, but running them locally is faster feedback and keeps main green.

# Check state and pull first
git status -sb
git pull --rebase origin main

npm ci                              # first time / when package-lock changed
npm run test:unit                   # unit + contract
npm run test:smoke                  # main paths
npm run test:characterization       # recorded behaviour + golden master
npm run test:visual                 # screenshot compare (needs Docker running)
npm test                            # the whole suite (optional, before a big release)
npm run build:pages                 # try building dist/ as Pages does

If the visual test fails because the UI really changed

Baselines must be generated in Docker so they are Linux like CI (Windows images will not match). Regenerate them and look at the images before committing.

npm run test:visual:update          # regenerate baselines in Docker (Linux, same as CI)
git status -sb tests/__screenshots__    # look at the changed images before committing

If you edited docs

Test counts change often. Recount before quoting numbers in docs: npx playwright test --list · npm run test:unit

3 · Commit and push

Write commit messages as <type>: <description>, where type is feat, fix, refactor, docs, test, chore, perf or ci.

git status -sb                                 # what changed?
git add app/index.html docs/ .github/pages/    # name the files, no git add -A
git diff --cached --stat                       # one more look
git commit -m "feat: add the user journey and release guide pages (th/en)"
git push origin main

4 · Deploy to Cloudflare Pages

Two workflows start by themselves after a push.

gh run list --limit 5                   # see the runs that just started
gh run watch                            # pick one and follow it live
gh run list --workflow "Publish site" --limit 3

Only changed tests/ or unit/ and the site did not update?

That is expected: the paths do not match Publish site. Trigger it yourself if you want a deploy:

gh workflow run cloudflare-pages.yml --ref main    # deploy by hand (no new commit needed)
gh run watch

Confirm the new site is live

curl -sI https://testover.pages.dev/docs/release-guide.html | head -1   # expect 200
git rev-parse --short HEAD                                              # compare with the commit on /status/

• App: testover.pages.dev → the bottom-right badge must show the new version (hard refresh if it is stale).
• The /status/ hub shows the deployed commit and the commit the reports came from.
• New docs: /docs/<name>.html must return 200 in both Thai and English.

The repo needs the secrets CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (the project name comes from the variable CLOUDFLARE_PROJECT_NAME, default testover).

Rolling back a bad deploy

git revert <sha>                        # undo one commit without rewriting history
git push origin main                    # Publish site runs again by itself

The whole thing in one block

Steps 2–4 together (do step 1 by hand first). It stops at the first failing command.

# The full set for a release (Git Bash); edit the commit message first
set -e
git pull --rebase origin main
npm run test:unit && npm run test:smoke && npm run test:characterization
npm run build:pages
git add app/index.html docs/ .github/pages/
git commit -m "feat: <what changed>"
git push origin main
gh run watch

Rules when adding or editing docs

• Every page ships in two languages: name.html (Thai) and name.en.html (English), with a language switch in the header and footer. Numbers must match.
• File names use lowercase letters, digits, - and . only, otherwise the server answers 404.
• Include the topnav like the other pages (in-page sections on the left, links to other pages on the right) and support light/dark and phone widths.
• Link it in: add it to the “Read next” list of overview.html / overview.en.html and to .github/pages/index.html.
• Record it in the change log with a line starting Docs: (see section 1).
• A new doc touches docs/**, so it triggers the automatic deploy.

Common problems