Codap V3 Build

CODAP v3 Build & Release

Overview

Interactive workflow for CODAP v3 releases. Guides you through Jira setup, release notes generation, version updates, PR creation, tagging, and deployment.

Quick Reference

Getting Started

When invoked, introduce the skill:

This skill will walk you through the process of building a release of CODAP v3. The process has 6 phases:

1. Prepare the Release - Set up Jira version and gather context
2. Prepare Release Notes - Interactive walkthrough to create CHANGELOG entry
3. Update Version Files - Update package.json, versions.md, CHANGELOG.md
4. Create Release PR - Build, capture asset sizes, create PR
5. Tag - After PR merge, create git tag (triggers the S3 build)
6. Deploy - Stage, QA, deploy to production, then publish the GitHub release

Are you ready to proceed?

Wait for user confirmation before starting Phase 1.

Approval Gates

Every action below changes shared state that other people see or depend on. For each one:

1. Show exactly what will happen: the full command, the Jira issues and fields, or the full message text.
2. Wait for the user's approval.
3. Do it, then read the result back (the run's outcome, the stored Jira value, the posted message) and report it.

An approval covers only the actions it names. Approving the staging deploy does not approve the Slack post that follows it, and "go ahead with everything" early in the session does not lift later gates.

Not gated: reads, builds, local commits, and previews posted to the developer's own Slack self-DM (Slack Posts).

Phase 1: Prepare the Release

Goal: Create Jira release version and gather context.

Steps

1. Check workspace status:

   git status

   • If there are modified/staged files, ask user to: Stash / Commit / Discard
   • Untracked files are okay to leave

2. Ensure on main branch with latest:

   git checkout main
   git pull

3. Get current build number:

   cat v3/build_number.json

   Needed for the version string only in the pre-release phase (see step 6), but always worth showing as context.

4. Get previous release tag:

   git tag --sort=-creatordate | head -5

5. Show context to user:

   • Display last 3 releases (version and date)
   • Show current build number from build_number.json

6. Determine recommended version string:

   CODAP v3 has two versioning conventions, one per development phase. Identify the current phase from the newest release tag, then apply that phase's rule.

   git tag --sort=-creatordate | head -3

   Phase	You are here when…	Version format	Rule
   Production release	The newest release tag is plain semver with no prerelease suffix (3.0.4, 3.1.2)	MAJOR.MINOR.PATCH	Increment from the last released version: patch for bug fixes, minor for new features, major for breaking changes. Example: after 3.0.4 → 3.0.5.
   Pre-release development	The newest release tag carries a prerelease suffix (-beta, -rc, -pre)	{major}.{minor}.{patch}-{suffix}.{buildNumber}	Use build number + 1 (it auto-increments when the release PR merges), carrying over the previous tag's version prefix and suffix. Example: newest tag 3.0.0-beta.2662 with build 2662 → 3.0.0-beta.2663.

   The build number is part of the version string ONLY in the pre-release phase. In the production phase the build number still exists and still increments, but it is independent of the version — do not derive the version from build_number.json. (At the 3.0.5 release the build number was 2956, heading to 2957 on merge, while the version was 3.0.5. The two are unrelated and will never match again.)

   CODAP v3 entered the production phase at 3.0.0 on 2026-06-04. The pre-release rule is retained because the project may re-enter a pre-release phase for a future major version (e.g. a 4.0.0-beta.N series), at which point it applies again.

   Exception — starting a new prerelease series. Inferring the phase from the newest tag is reliable within a phase but blind to the moment you deliberately switch. When the next major begins its prerelease series, the newest tag is still production semver (e.g. 3.1.4), so the rule above would wrongly say "production, bump the patch" instead of 4.0.0-beta.N. A tag can't signal an intent to change phase. So before applying the rule, ask the user whether this release starts a new prerelease series for a new major version. If yes, switch to the pre-release convention and confirm the intended prefix (4.0.0) and suffix (-beta) with them rather than inferring.

   Which component to bump is a judgment call about the release's contents, not a mechanical rule — propose one and confirm it with the user along with the rest of the Jira release details (step 8). Count only what users can see: work behind a feature flag, logging, and docs don't make a release minor, and by convention neither does a new translation or language.

7. Get previous release date from Jira (for start date default)

8. Ask user for Jira release details:

   Field	Default	Options
   Version name	The phase-appropriate next version from step 6	Production phase: patch / minor / major bump. Pre-release phase: previous suffix + new build number
   Start date	Previous release date	User can modify
   Release date	Today's date	Today / Tomorrow / Custom future date
   Description	Version {version}	User can modify

   Note: The release date chosen here is used throughout the process:

   • CHANGELOG.md header date
   • versions.md entry date
   • Jira release date

9. Ensure the Jira release version exists (status: Unreleased).

   The Atlassian MCP tools cannot create a version or edit its release date — they expose no version-management tool. This step is the user's to perform, in the Jira UI (CODAP → Releases). Setting issue Fix Versions (Phase 2, step 9) works fine through MCP; it is only the version object itself that is out of reach.

   • Check whether it already exists first — Jira automation may have created the version (and a Release {version} tracking issue) ahead of time. Ask the user to check Jira → CODAP → Releases; that is the only reliable check. Querying the fixVersions field via JQL is a weak fallback: it can only surface versions already assigned to at least one issue, so a freshly created version with nothing assigned to it — the very case this step is looking for — will not appear. Absence from JQL is not evidence the version is missing.
   • If it exists, confirm its release date matches the date agreed in step 8; if it doesn't, ask the user to correct it.
   • If it doesn't exist, ask the user to create it with the agreed name, dates, and description, and to confirm once done.

   The date only has to be correct before the release is marked Released in Phase 6, so this need not block the rest of the workflow.

10. Put the release tracking issue in the current sprint. Jira automation creates a Release {version} issue (type Release) along with the version, and it lands in the backlog. Once the user confirms the version exists, have a subagent find it and the active sprint:

    project = CODAP AND issuetype = Release AND fixVersion = "{version}"   -- with customfield_10020
    project = CODAP AND sprint in openSprints()     -- customfield_10020, maxResults 50

    If the tracking issue's customfield_10020 already holds the active sprint, report that and skip the edit (the user may have moved it already). Sprint IDs are not sequential, so read the active sprint's id, name, and endDate from customfield_10020 rather than guessing; scan all results, since an issue can carry several sprints. If more than one sprint is active, or the active sprint ends before the release date, ask which sprint to use.

    Setting the sprint is a gated Jira edit: show the issue key, its summary, and the sprint name and ID, then set customfield_10020 to the sprint's ID (a plain integer, not an object) with editJiraIssue, and re-fetch the field to confirm it. If no tracking issue exists, say so; don't create one.

Phase 2: Prepare Release Notes

Goal: Generate CHANGELOG entry with user-selected titles.

Steps

1. Get PRs since last release:

   git log <last-tag>..HEAD --oneline | grep -E '\(#[0-9]+\)|Merge pull request #[0-9]+'

   Note: This finds both regular merge commits AND squash-merged PRs (which include (#123) in the commit message). Using --merges alone misses squash merges.

2. Get PR details from GitHub:

   gh pr view <number> --json number,title,headRefName

3. Match PRs to Jira stories by CODAP-XXX ID:

   • Check branch name first (most reliable, e.g., CODAP-1027-inbounds-url-param)
   • Then PR title (e.g., CODAP-1027: Implement inbounds parameter)
   • Use caution with PR descriptions - they may reference related stories (e.g., "Follow-up to CODAP-XXX") that aren't the primary story for this PR
   • Extract unique CODAP-XXX IDs

4. For each matched item, fetch:

   • Jira story details (summary, issue type, current status)
   • PR title from GitHub
   • Generate AI-suggested title (concise, user-focused)

5. Interactive walkthrough for each item:

   IMPORTANT - NO SHORTCUTS:

   • Do NOT ask user to approve the entire list at once
   • Do NOT batch items together (e.g., "approve these 3 items")
   • Do NOT skip showing title options
   • ALWAYS go through items ONE BY ONE, presenting all title options for each

   IMPORTANT - PUT THE TABLE IN THE QUESTION: Text written in the same turn as an AskUserQuestion call is not shown to the user, so a table output just before the question is invisible and the user has nothing to decide from. Put each item's table in the preview of every option of the Section question (previews render as monospace markdown beside the options), and put the candidate titles in the option descriptions of the Title question.

   The preview for each item:

   Item 1/8: CODAP-1027 (Story) — Jira: Done
   
   | Source        | Title       |
   |---------------|-------------|
   | AI suggestion | {ai_title}  |
   | Jira          | {jira_summary} |
   | PR            | {pr_title}  |
   
   PR #NNNN. {one or two lines of context: what the user would see, whether it is
   flag-gated, anything that bears on the section choice}

   Note: Strip Jira IDs from PR titles before presenting (e.g., "CODAP-138: Fix point color" → "Fix point color")

   Jira status notice (if not Done): append the status to the preview's first line with a warning indicator, e.g. Item 1/8: CODAP-1027 (Story) — Jira: In Project Team Review ⚠️. The user can choose to exclude the story via the Section question.

   Ask using AskUserQuestion (Section and Title are TWO SEPARATE CALLS so Title is skipped if Exclude):

   Section question:

   • Question: "Item N/M: CODAP-XXXX ({type}) — which section?"
   • Options: Features / Bug Fixes / Under the Hood / Exclude, with the recommended one first
   • Recommend from what users will see, not from the issue type alone. Read the PR body when the type and the change disagree:
     • Work behind a feature flag → Exclude. But check each PR: a story in a flag-gated epic can still ship an ungated, visible change (in 3.1.1, a Format palette redesign and a legend-behavior fix both came from the flag-gated point-shapes epic).
     • A story that fixes broken behavior → Bug Fixes.
     • A fix to something no released version has shipped → Exclude; users never saw the bug (e.g. corrections to a language first released in the same version).
     • Docs, plans, logging, and CI/deploy infrastructure → Exclude.
     • Otherwise: Features for Stories, Bug Fixes for Bugs.
   • If user types in "Other", interpret as an instruction (e.g., "go back to previous item") and handle accordingly

   If Section is NOT Exclude - ask Title question:

   • Question: "CODAP-XXXX — which title? (or type your own in 'Other')"
   • Options: AI suggestion / Jira / PR, each with its full title as the option description (no "Custom" - user types preferred title in built-in "Other")
   • If the chosen section changes the framing (e.g. a Story moved to Bug Fixes), reword the AI suggestion to match and say so in the question
   • If user types in "Other", use their text as the title
   • Title option order must ALWAYS be: AI suggestion, Jira, PR (both in the preview and in question options)
   • Stories included in release notes will have their Fix Version updated automatically (tracked for step 9)

   If Section IS Exclude - ask Fix Version question:

   • Question: "Should CODAP-XXXX's Fix Version be set to this release?"
   • Options: Yes / No, with the recommended one first
   • Recommend Yes when the story's work is complete in this release, even if it isn't user-facing (flag-gated work, docs, infrastructure) — it should still be tracked in Jira.
   • Recommend No when the story is still In Progress or is an epic with open stories: more work will follow, so it isn't "fixed" in this version.
   • If Yes: Add to Fix Version update list (step 9) even though excluded from release notes
   • If No: Do not update Fix Version (e.g., if the story was fixed in a prior release, or the PR isn't part of this release)

   After selection, confirm:

   ✓ CODAP-1027 → Features: "Selected title here"

6. For PRs without Jira IDs:

   • Show PR title only
   • Default recommendation: Exclude (Recommended) for docs, dependencies, maintenance
   • Option to include in Under the Hood if relevant
   • No Fix Version to update (no Jira story)

7. Generate CHANGELOG markdown after all items are processed:

   ## Version {version} - Month Day, Year
   
   ### ✨ Features & Improvements:
   - **CODAP-XXX:** Title here
   - **CODAP-YYY:** Another title
   
   ### 🐞 Bug Fixes:
   - **CODAP-AAA:** Fix description
   - **CODAP-BBB:** Another fix
   
   ### 🛠️ Under the Hood:
   - **CODAP-ZZZ:** Internal improvement

   Rules:

   • Order items by numeric Jira ID (223 before 1027)
   • Only include sections that have items
   • Use the release date from Phase 1
   • Date format: Month Day, Year (e.g., February 1, 2026)

8. Present generated markdown for approval:

   Show the complete CHANGELOG entry as a markdown code block and end the turn with a plain question — do not use AskUserQuestion here. The entry is too long for an option preview, and text in the same turn as a question isn't shown, so the user would be asked to approve notes they can't see. Ask whether to approve, edit an item (section or title), or reorder. The user often reviews the whole entry for consistency at this point (e.g. capitalization, or similar items landing in different sections), so expect edits.

   In the same message, list the issues step 9 will set the Fix Version on, so a single reply can approve both the notes and that gated Jira edit.

   Note: Mention that Asset Sizes will be added in Phase 4 after the build.

9. Update Jira Fix Versions for all stories where user approved the update (during step 5).

   This is a gated action: list the story IDs and the version first, and wait for approval.

   IMPORTANT - Context Management: Jira MCP responses can be verbose and consume significant context. Delegate this bulk operation to a subagent:

   Use the Task tool to update Fix Versions for all approved stories. Provide the subagent with:

   • The list of CODAP-XXX story IDs to update
   • The version string to set (e.g., 3.0.5)

   The subagent should report back ONLY:

   • Success/failure count (e.g., "Updated 8/10 stories successfully")
   • IDs of any stories that failed (e.g., "Failed: CODAP-123, CODAP-456")

10. Check the fix version from the Jira side. Steps 1–9 match only from PR to story, so a story that carries the fix version but has no merged PR in the release range goes unnoticed. Have a subagent run this JQL and report key, summary, issue type, status, assignee, and Project Team Approver for each result:

    project = CODAP AND fixVersion = "{version}" ORDER BY key

    Compare the results with the stories matched in step 3 and show the user:

    • Stories on the version with no merged PR in the range. Ask whether each belongs in this release (e.g. a story with no code, or a PR merged before the previous tag), or whether its Fix Version should be removed. Removing it is a gated Jira edit. The Release {version} issue (type Release) that Jira automation creates with the version is expected here and needs no action.
    • Stories that are not Done, grouped by status. These are expected at this point (most stories sit in "In Project Team Review" until after the release), so this is informational. They are checked again before the version is marked released (Phase 6).
    • Stories whose PR is merged but whose status is earlier than In Project Team Review (e.g. still "Ready for Merge"). Point these out. Before moving one to In Project Team Review (a gated Jira edit), check that it has testing instructions the Project Team Approver can follow, and offer to draft them from the PR if not.

    This check and the read-back of step 9 are the same query, so one subagent can do both.

    JQL can query this reliably now that step 9 has assigned the version to issues; the caveat in Phase 1, step 9 applies only to a version with no issues yet.

Phase 3: Update Version Files

Goal: Sync translations, update all version-related files, and create release branch.

IMPORTANT — Working Directory Awareness:

• Scripts in v3/scripts/ use cd v3 internally, which changes the shell's working directory for subsequent commands in the same Bash call.
• After running a v3 script, always verify your working directory with pwd before running git commands.
• All git commands must be run from the repository root (/path/to/codap), not from v3/.
• If a git diff or git status command produces no output, do NOT assume "no changes" — verify by checking the working directory and trying again with correct paths. Empty output from git commands that should show changes is a red flag that something is wrong.

Steps

IMPORTANT — Branch policy: Never commit directly to main. The release branch must be created before any commits (translations, version files, etc.).

1. Create release branch:

   git checkout -b release-{version}

   Branch naming rules:

   • Pattern: release-{version} where {version} is from Phase 1 (e.g., release-3.0.5)
   • Do NOT use / in branch names
   • Do NOT invent your own pattern

2. Sync translations with POEditor:

   V3 owns all string pushes to POEditor — both DG.* and V3.* keys. All English strings live in a single file: src/utilities/translation/lang/en-US.json5.

   API Token: All scripts resolve the token in order: -a argument > ~/.porc > $POEDITOR_API_TOKEN env var. Only ask the user for a token if none of these are configured.

   2a. Preview English string changes before pushing:

   Before pushing, pull the current English strings from POEditor and diff them against the local en-US.json5 so the user can validate the changes.

   cd v3
   # Pull current English strings from POEditor to a temp file
   ./scripts/strings-pull.sh -p 125447 -l en-US -o /tmp
   # Convert local JSON5 to JSON for comparison
   node -e "
   const fs = require('fs');
   const JSON5 = require('json5');
   const data = JSON5.parse(fs.readFileSync('src/utilities/translation/lang/en-US.json5', 'utf8'));
   fs.writeFileSync('/tmp/en-US-local.json', JSON.stringify(data, null, 4) + '\n');
   "
   # Detailed diff showing new keys, changed values, and keys only in POEditor
   node -e "
   const poeditor = require('/tmp/en-US.json');
   const local = require('/tmp/en-US-local.json');
   const changed = [], newKeys = [], missingLocally = [];
   for (const k of Object.keys(local)) {
     if (!(k in poeditor)) newKeys.push(k);
     else if (poeditor[k] !== local[k]) changed.push({key: k, old: poeditor[k], new: local[k]});
   }
   for (const k of Object.keys(poeditor)) {
     if (!(k in local)) missingLocally.push(k);
   }
   console.log('=== VALUE CHANGES (' + changed.length + ' keys) ===');
   changed.forEach(c => {
     console.log('  ' + c.key);
     console.log('    POEditor: ' + JSON.stringify(c.old));
     console.log('    Local:    ' + JSON.stringify(c.new));
     console.log();
   });
   console.log('=== NEW KEYS (' + newKeys.length + ' keys) ===');
   newKeys.forEach(k => console.log('  ' + k + ': ' + JSON.stringify(local[k])));
   console.log();
   console.log('=== KEYS IN POEDITOR BUT NOT LOCAL (' + missingLocally.length + ' keys) ===');
   missingLocally.forEach(k => console.log('  ' + k + ': ' + JSON.stringify(poeditor[k])));
   "

   Show the diff to the user. Common expected changes:

   • New keys added since the last release (lines only in local)
   • Updated string values

   Red flags to call out:

   • Keys present in POEditor but missing locally (would NOT be deleted since sync_terms=0, but worth noting)
   • Unexpected value changes to existing keys

   Decide whether to push — based solely on whether English strings changed:

   • No value changes AND no new keys (English strings unchanged): skip the push entirely — do not ask. There is nothing to upload, so the push (2b) would be a no-op. Note that English is unchanged and go straight to the mandatory pull (2c).
   • There ARE English string changes (new keys or changed values): show the diff and ask the user to approve the push before proceeding to 2b.

   2b. Push English strings to POEditor (only when 2a found English changes):

   ./scripts/strings-push-project.sh

   This pushes all strings from en-US.json5 (both DG and V3 keys) to POEditor. The push is additive (sync_terms=0) — it adds new terms and updates existing values but never deletes terms. Push first so that the subsequent pull includes any new keys added since the last release.

   2c. Pull non-English translations:

   ./scripts/strings-pull-project.sh

   This pulls translated strings for all supported languages. Report results to the user (the streaming output may be collapsed in the UI).

   Always run the pull — never skip it and never ask whether to pull. Every build must pull from POEditor, because translators may have added or updated non-English strings since the last release even when the English strings are unchanged. (The push in 2b is conditional; this pull is not.)

   2d. Verify and commit pulled translations:

   Return to the repository root before running git commands:

   cd /path/to/codap   # repository root, NOT v3/
   git status -- v3/src/utilities/translation/lang/

   Report results to the user. Every language normally gains the new English keys from 2b (untranslated keys arrive with the English text). Also review changes to existing translations — values translators edited in POEditor since the last release. These go straight into the release, and nothing else checks them. List them, filtering out the new keys:

   git diff -U0 -- v3/src/utilities/translation/lang/ | grep -E '^(\+\+\+|[-+] )' \
     | grep -vE '<new-key-pattern>'   # e.g. 'pointShape|section\.graph|...' from 2a's NEW KEYS

   A changed line can also be just a trailing comma, where a new key was appended after what used to be the last entry; ignore those. Show the user each changed value, old → new, and flag anything that looks wrong: typos, broken placeholders (%@), lost punctuation. In the 3.1.1 release, two French typos arrived this way.

   If a translation needs fixing, fix it in POEditor, not in the local file (the next pull would overwrite a local fix), then re-run 2c. Fixing it is a gated action. Write the corrections to a JSON file and call the POEditor API; ~/.porc defines API_TOKEN:

   # fixes.json: [{"term":"<key>","context":"","translation":{"content":"<corrected text>"}}]
   source ~/.porc
   curl -s -X POST https://api.poeditor.com/v2/translations/update \
     -d api_token="$API_TOKEN" -d id=125447 -d language=<lang> --data-urlencode data@fixes.json
   # expect: "translations":{"parsed":N,"updated":N}

   After re-running 2c, grep the language file to confirm the corrected values arrived.

   Then commit:

   git add v3/src/utilities/translation/lang/
   git commit -m "Update translations from POEditor"

   Zero-width space handling: POEditor treats truly empty strings as "untranslated," so the scripts convert between empty strings and zero-width spaces (\u200b) at the boundary:

   • Push (strings-push.sh): "" → "\u200b" before uploading
   • Pull (strings-pull.sh): "\u200b" → "" after downloading

   The source file (en-US.json5) and all runtime language files use "" for intentionally blank strings — zero-width spaces should never appear in the repository.

3. Update package.json version:

   cd v3
   npm version --no-git-tag-version {version}

   IMPORTANT: Use the npm version command - do NOT manually edit package.json. The npm command updates both package.json AND package-lock.json.

4. Update versions.md:

   Add new row at top of versions table (using release date from Phase 1):

   | [{version}](https://codap3.concord.org/version/{version}/) | Month Day, Year |

5. Update CHANGELOG.md:

   • Insert content from Phase 2 at top (after # Changelog heading)
   • Asset Sizes section added in Phase 4

6. Stage version files:

   git add v3/package.json v3/package-lock.json v3/versions.md v3/CHANGELOG.md

Phase 4: Create Release PR

Goal: Build, capture asset sizes, commit, and create PR.

Steps

1. Run build:

   cd v3 && npm run build

2. Get asset sizes:

   ls -la v3/dist/assets

   • Find main.*.css file, get its size
   • Find all index.*.js files, use the largest one
   • Strip hashes for display: index.f6eac39a783c91ae9ea5.js → index.js

3. Calculate % change:

   • Read previous sizes from top entry in CHANGELOG.md
   • Calculate: ((new - old) / old) * 100
   • Format: X.XX%, <0.01% for very small increases, negative for decreases (e.g., -0.50%)

4. Add Asset Sizes to CHANGELOG:

   ### Asset Sizes
   |      File |          Size | % Change from Previous Release |
   |-----------|---------------|--------------------------------|
   |  main.css |  XXXXXX bytes |                          X.XX% |
   |  index.js | XXXXXXX bytes |                          X.XX% |

5. Commit and push:

   git add v3/CHANGELOG.md
   git commit -m "Release {version}"
   git push -u origin release-{version}

   Note: Only commit the version files (package.json, package-lock.json, versions.md, CHANGELOG.md). Do not commit the dist/ build output.

   The push and the PR creation (step 6) are gated. Show the branch, the PR title, and the full PR body, and get one approval covering both.

6. Create PR with labels:

   gh pr create \
     --title "Release {version}" \
     --body "{release_notes_from_phase_2}" \
     --label "v3" \
     --label "run regression"

7. Inform user:

   PR created: {url}

   CI is running. The run regression label triggers the full Cypress test suite.

   After CI passes and PR is reviewed/merged, run /codap-v3-build tag to continue.

8. If CI fails or stalls, check for a GitHub outage before suspecting the release. During the 3.1.1 release, a GitHub Actions incident made jobs wait for runners that never came: they ran no steps and were cancelled exactly 15 minutes after being queued, while jobs that did get runners passed slowly. That pattern means the infrastructure, not the code:

   gh run view <id> --json jobs \
     --jq '.jobs[] | "\(.name)\t\(.conclusion)\t\(.startedAt) -> \(.completedAt)\t\(.steps|length) steps"'
   curl -s https://www.githubstatus.com/api/v2/incidents/unresolved.json \
     | python3 -c "import json,sys; [print(i['name'], i['status'], i['created_at']) for i in json.load(sys.stdin)['incidents']]"

   If an Actions incident is open, poll the status API in the background (e.g. every 3 minutes) until it clears, then re-run the affected runs (gh run rerun <id>, or --failed for only the cancelled jobs) and watch them with gh run watch <id> --exit-status.

Phase 5: Tag

Goal: After PR merge, create the git tag that triggers the S3 build.

Do NOT create the GitHub release here. Publishing the GitHub release at tag time confused external users: they saw a published release for a version that was not yet available in production (staging QA can take 1+ days). The GitHub release is created later, in Phase 6, only after the build is live in production. The tag still must be pushed now, because the tag push is what triggers the CI build that deploys to S3 (needed for staging).

Prerequisite: Release PR must be merged, and the automatic "Increment the build number" commit that follows the merge must have landed on main (see step 2).

Steps

1. Checkout main and pull:

   git checkout main
   git pull

2. Verify the build-number increment commit has landed — do NOT skip this:

   Merging the release PR triggers an automation that pushes an "Increment the build number" commit to main. That increment commit is the one to tag — not the Release {version} merge commit.

   git log --oneline -2

   The output must show the increment commit sitting on top of the release merge:

   f999f1445 Increment the build number     <- tag THIS one (HEAD)
   936451ef5 Release {version} (#NNNN)

   If HEAD is still the Release {version} merge commit, the automation has not pushed yet. Wait, re-run git pull, and check again until the increment commit appears.

   Why this matters: tagging immediately after the merge, before the increment lands, points the tag at the release merge commit instead. This has happened before. The resulting build carries the wrong build number, and undoing it means deleting the tag and its S3 deploy. Every correct release tag (3.0.0 through 3.0.3) points at an "Increment the build number" commit — use that as your check.

3. Create the annotated tag, confirm its target, then push it. Create it locally and check that it is on the increment commit:

   git tag -a {version} -m "Version {version}"
   git log -1 --format='%h %s' {version}
   # expected: <sha> Increment the build number

   The push is gated. Show the tag, its commit, and the command, then:

   git push origin {version}
   git ls-remote --tags origin '{version}^{}'   # the commit it points at; must match
   git rev-list -n1 {version}

   The tag push triggers a CI build that deploys to S3. The GitHub release is not created until after the production deploy (Phase 6).

4. Watch the tag's CI run until the S3 deploy finishes. The tag push starts the "Continuous Integration (CODAP v3)" workflow (v3.yml), whose S3 Deploy job publishes version/{version}/. Find the run for the tag's commit; it can take a few seconds to appear, so retry if the list is empty:

   gh run list --workflow v3.yml --branch {version} \
     --json databaseId,headSha,status,createdAt
   git rev-list -n1 {version}   # the run's headSha must match this
   gh run watch <id> --exit-status

   Then confirm the version folder is served:

   curl -s -o /dev/null -w '%{http_code}\n' https://codap3.concord.org/version/{version}/
   # expected: 200

   Do not trigger the staging workflow until the run has succeeded and the folder returns 200. The staging workflow copies version/{version}/index-top.html, so it fails if the S3 deploy hasn't finished. If the run fails, stop and show the user the failed job (gh run view <id> --log-failed).

5. Inform user:

   Tag pushed and deployed to S3: https://codap3.concord.org/version/{version}/ (The GitHub release will be created later, after the production deploy, so external users don't see a release for a version that isn't live yet.)

   Ready to deploy to staging? (Or run /codap-v3-build deploy {version} later.)