Skip to content

chore: unify version sync workflow and make root VERSION the canonical source#112

Merged
zapabob merged 2 commits intomainfrom
codex/establish-canonical-version-source
Mar 20, 2026
Merged

chore: unify version sync workflow and make root VERSION the canonical source#112
zapabob merged 2 commits intomainfrom
codex/establish-canonical-version-source

Conversation

@zapabob
Copy link
Owner

@zapabob zapabob commented Mar 20, 2026

Motivation

  • Establish a single canonical release version source (root VERSION) so displayed/manifests/docs stay consistent.
  • Provide machine-readable metadata (fork_version / upstream_base) to disambiguate fork vs upstream and allow automated decision logic.
  • Make the current 3.x release docs immediately obvious while archiving legacy 2.x history to avoid confusion.
  • Provide an automated sync/check workflow so future bumps propagate reliably to manifests and docs.

Description

  • Adopt the root VERSION as the canonical source and add version-metadata.json containing fork_version, upstream_base, release lines, and sync targets.
  • Add scripts/sync-version.mjs to propagate the canonical version into package.json files, the Rust workspace package version (codex-rs/Cargo.toml), README.md badge/managed block, CHANGELOG.md, and releases/RELEASE_NOTES.md, and to provide a --check mode for validation.
  • Split legacy v2.x artifacts into releases/legacy/v2.x/CHANGELOG.md and releases/legacy/v2.x/RELEASE_NOTES.md and update root changelog/release-notes to be the current v3 document.
  • Wire the sync script into root npm scripts (version:sync and version:check), update scripts/bump-version.ps1 to recommend running the sync flow, and bump visible package versions (root package.json and packages/protocol-client/package.json) and the Rust workspace package version to 3.0.0 to match VERSION.

Testing

  • Ran node scripts/sync-version.mjs --check and it returned success (no drift detected).
  • Validated scripts/sync-version.mjs with node --check scripts/sync-version.mjs (syntax check) and it passed.
  • Executed git diff --check over modified files to ensure no whitespace/conflict markers and found no issues.
  • Ran a custom Node verification script that asserts VERSION, root package.json, packages/protocol-client/package.json, version-metadata.json and codex-rs/Cargo.toml all match and it succeeded.

Codex Task

@vercel
Copy link

vercel bot commented Mar 20, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
codex Error Error Mar 20, 2026 2:22pm

@zapabob zapabob merged commit 4f72c23 into main Mar 20, 2026
17 of 48 checks passed
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9e86989d55

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +120 to +121
/\[!\[Version\]\(https:\/\/img\.shields\.io\/badge\/version-v[^\]]+\]\(https:\/\/github\.com\/zapabob\/codex\/releases\/tag\/v[^)]+\)/,
`[![Version](https://img.shields.io/badge/version-v${canonicalVersion}-blue)](https://github.com/zapabob/codex/releases/tag/v${canonicalVersion})`,

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Generate README release links for the published rust-v tags

The new sync template hard-codes .../releases/tag/v${canonicalVersion}, but the repo’s release pipeline still publishes Rust releases under rust-v* (.github/workflows/rust-release.yml:4-12,35-45), and both installer scripts resolve/download rust-v${version} assets (scripts/install/install.sh:104-126, scripts/install/install.ps1:38-45,67-79). As a result, every future version:sync run will regenerate a README badge link that points at a non-existent release page instead of the actual published artifacts.

Useful? React with 👍 / 👎.

const changelogArchive = metadata.sync_targets.archives.changelog;
const releaseArchive = metadata.sync_targets.archives.release_notes;

const changelog = `# Changelog\n\nCurrent canonical version: **v${canonicalVersion}**.\nCanonical source: \`VERSION\`. Fork/upstream disambiguation lives in \`version-metadata.json\`.\n\n## Current Release — v${canonicalVersion} (${releaseDate})\n\n> This root changelog is the **current release line only**.\n> Legacy v2.x history has been moved to \`${changelogArchive}\` to make the latest release immediately obvious.\n\n### Changed\n\n- Adopted **root \`VERSION\`** as the single canonical version source for release-visible artifacts.\n- Added a machine-readable version metadata file with \`fork_version\` and \`upstream_base\` for fork/upstream conflict resolution.\n- Added generated sync automation for root/package manifests, workspace Cargo version, README display version, release notes, and changelog headers.\n\n### Docs\n\n- Split legacy **v2.x** history from the current **v3.x** release line.\n- Marked the root release notes and changelog as the current release documents.\n- Standardized the displayed release version across README badges and package metadata.\n\n## Historical Release Lines\n\n- **v2.x archive**: \`${changelogArchive}\`\n- **Legacy release notes**: \`${releaseArchive}\`\n`;

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Stop hardcoding the release lines in generated docs

These generated templates bake in v3.x as the current line and v2.x as the legacy line instead of deriving them from metadata. If the next major release bumps VERSION to 4.0.0, node scripts/sync-version.mjs will still publish a changelog/release-notes set that says the current release line is v3.x, which contradicts the stated goal that future bumps propagate reliably from the canonical version source.

Useful? React with 👍 / 👎.

Comment on lines +65 to +66
Write-Host " 1. node scripts/sync-version.mjs を実行" -ForegroundColor Yellow
Write-Host " 2. node scripts/sync-version.mjs --check で整合性確認" -ForegroundColor Yellow

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Include release_date in the new version-bump workflow

The new recommended flow only tells maintainers to update VERSION and run scripts/sync-version.mjs, but sync-version.mjs renders README/changelog/release notes from version-metadata.json.release_date (scripts/sync-version.mjs:54,107-112). That means the next release will silently keep showing the previous release date unless someone remembers to hand-edit version-metadata.json, so the automated sync path now produces stale release metadata by default.

Useful? React with 👍 / 👎.

@github-actions
Copy link


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

@github-actions github-actions bot locked and limited conversation to collaborators Mar 20, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant