fix(openapi): prevent make dev from rewriting api.yaml version on event

[axsseldz]

📝 Summary

make dev runs fe-codegen, which regenerates packages/openapi/api.yaml.
During generation, info.version is set from marimo’s runtime/package version (pyproject.toml), so if api.yaml is stale it gets rewritten

Closes #8333.

🔍 Root Cause

• make dev depends on fe-codegen.
• fe-codegen runs marimo development openapi > packages/openapi/api.yaml.
• OpenAPI info.version is emitted from __version__ (package metadata from pyproject.toml).
• If committed api.yaml version is behind, local dev triggers a diff.

🔍 Description of Changes

• Added scripts/check_openapi_version_sync.py to verify:
  • pyproject.toml [project].version
  • packages/openapi/api.yaml info.version
• Added a local pre-commit hook in .pre-commit-config.yaml:
  • hook id: openapi-version-sync
  • runs only when relevant files change
• Added PR CI workflow .github/workflows/test_openapi_version_sync.yaml:
  • runs the same check
  • path-filtered to relevant files only

📋 Checklist

• I have read the contributor guidelines.
• For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable).
• Tests have been added for the changes made.
• Documentation has been updated where applicable, including docstrings for API changes.
• Pull request title is a good summary of the changes - it will be used in the release notes.

[updated after latest changes]

CC: @mscolnick @nojaf

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Feb 23, 2026 10:40pm

[nojaf]

@axsseldz can you investigate when this version bumps?
Can we have a CI check for this? Or some pre-commit hook that only hooks in when the relevant file changes?

[axsseldz]

@axsseldz can you investigate when this version bumps? Can we have a CI check for this? Or some pre-commit hook that only hooks in when the relevant file changes?

the version in packages/openapi/api.yaml changes when OpenAPI gets regenerated, and make dev always runs that regeneration step through fe-codegen, the generator sets info.version from marimo’s current package version in pyproject.toml, so if api.yaml is behind, it gets bumped automatically, which is what happened in this case, on pyproject.toml version was 0.19.11, that's why when running make dev it updated the api.yaml info.version, because this command runs fe-codegen.

i also added both checks, there is now a CI check that fails if pyproject.toml version and api.yaml info.version don’t match, and a local pre-commit hook that runs the same check but only when relevant files are changed.

--> right here i went back to 0.19.10 (outdated version) and ran the checks, and then went back again to 0.19.11, with pre-commit i suggest running make fe-codegen to generate the api.yaml file, but for the sake of this example i just updated it manually.

[nojaf]

@axsseldz great investigation! Keep it it!

[manzt]

Thanks for the PR!

Zooming out, it seems like the core issue is that when we bump the version in pyproject.toml and tag a release, we never regenerate api.yaml. So api.yaml is always one version behind each release.

This check catches the drift after the fact but doesn't prevent it. After every release, the first PR will either fail this check (and need a side change to fix it) or need a dedicated "bump api.yaml" commit, and even then, api.yaml will still have been behind for the release itself.

The question is whether info.version in api.yaml is meaningful or necessary. If so, we should regenerate the spec as part of the version bump and assert that only the version number changes. If not, the simplest fix is to stop embedding __version__ in the generated output.

[manzt]

Chatting with the team I think it's preferred if we just omit version from codegen. It doesn't do anything other than contribute to confusion/drift.

Would you be up for making that change?

[axsseldz]

Chatting with the team I think it's preferred if we just omit version from codegen. It doesn't do anything other than contribute to confusion/drift.

Would you be up for making that change?

Yes, no problem!, i'll send the changes asap 👍

[axsseldz]

hey @manzt i updated the PR based on your feedback, i removed info.version from OpenAPI codegen in commands.py and regenerated api.yaml, so the schema no longer tracks package release version, i also removed the temporary sync guard I had added, since there’s no version field left to sync.

[manzt]

Looks great. Thanks for the contribution!