bump-sdk-version

name	bump-sdk-version
description	Bump the FutureSearch SDK version across all files. Use when releasing a new SDK version, updating version numbers, or the user says bump version, release, version bump.

Bump SDK Version

Versioning Guidelines

We use semantic versioning (MAJOR.MINOR.PATCH) while at major version 0:

Bump	When	Examples
Patch (0.8.0 -> 0.8.1)	Bug fixes, docs changes, small tweaks, dependency updates	Fix a typo in output, update a dependency
Minor (0.8.1 -> 0.9.0)	New features, new operation types, API additions	Add a new operation, new SDK method, new MCP tool
Patch for breaking changes that are trivial to adapt	Rename a parameter, change a default	Rename max_rows to row_limit
Minor for breaking changes that require migration	Remove or restructure API surface	Remove an operation type, change return format

If unsure, ask the user which component to bump.

Files to Update

All paths are relative to futuresearch-python/. Update the version string in each:

1. pyproject.toml — project.version (the source of truth)
2. .claude-plugin/plugin.json — version
3. .claude-plugin/marketplace.json — plugins[0].version
4. gemini-extension.json — version
5. futuresearch-mcp/pyproject.toml — project.version AND dependencies (futuresearch>=X.Y.Z)
6. futuresearch-mcp/server.json — version AND packages[0].version
7. futuresearch-mcp/manifest.json — version
8. CITATION.cff — version AND date-released (set to today's date)
9. README.md — BibTeX version field in the citation block
10. stubs/everyrow/pyproject.toml — project.version AND dependencies (futuresearch>=X.Y.Z)
11. stubs/everyrow-mcp/pyproject.toml — project.version AND dependencies (futuresearch-mcp>=X.Y.Z)

After editing, regenerate the lock files. Run uv lock in futuresearch-python/ first:

cd futuresearch-python && uv lock

Then sync transitive lockfiles across the entire monorepo. The CI check check-uv-sync runs ./uv-all.sh sync --all-extras --dev --all-groups and will fail if any other workspace's uv.lock still references the old SDK version. Run it from the repo root:

cd <repo-root> && ./uv-all.sh sync --all-extras --dev --all-groups

Stage any additional lockfiles it touches alongside the bump.

Verification Steps

1. Run version consistency tests

cd futuresearch-python && uv run pytest tests/test_version.py -v

2. Search for stale version references

Search for the OLD version number to catch any files that were missed. Use --hidden (or equivalent) to include .claude-plugin/ and other dotfiles:

cd futuresearch-python && rg --hidden "OLD_VERSION" --glob '!.venv' --glob '!uv.lock' --glob '!*.pyc' --glob '!__pycache__'

Be sure to escape the . characters in the version number: "1\.2\.3".

Review any hits — some may be false positives: e.g., changelogs, migration notes, 3rd party packages.

3. Commit

Create a branch and commit with message: Bump SDK version to X.Y.Z

Important: Dedicated PR

Version bumps should be in their own PR — do not bundle them with feature or fix changes. The commit message and PR title should be: Bump SDK version to X.Y.Z

Publishing the release

Merging the bump PR does NOT publish. The publish pipeline lives in the public futuresearch/futuresearch-python repo's .github/workflows/publish.yaml and triggers on release: published only. After the bump PR merges:

1. Wait for sync-futuresearch-python to mirror the bump commit to the public repo (verify with gh api repos/futuresearch/futuresearch-python/commits/main --jq '.commit.message').

2. Create a GitHub Release with tag vX.Y.Z (note the v prefix) and the auto-generated changelog:

   gh release create vX.Y.Z \
     --repo futuresearch/futuresearch-python \
     --generate-notes \
     --latest
   

3. This kicks off publish.yaml, which:

   • Builds and uploads 4 wheels to PyPI (futuresearch, futuresearch-mcp, everyrow, everyrow-mcp)
   • Builds and attaches the .mcpb bundle to the release
   • Publishes to the MCP Registry (waits 30s for PyPI propagation first)

4. Watch the run:

   gh run list --repo futuresearch/futuresearch-python --workflow=publish.yaml --limit 1
   

Checklist

• All 11 files updated with new version
• CITATION.cff date-released set to today
• Dependency version floors updated (futuresearch>=X.Y.Z, futuresearch-mcp>=X.Y.Z)
• uv lock regenerated
• ./uv-all.sh sync --all-extras --dev --all-groups run from repo root; any updated transitive lockfiles staged
• uv run pytest tests/test_version.py passes
• rg --hidden "OLD_VERSION" shows no unexpected hits
• PR contains only version bump changes (no other features or fixes)
• After merge + sync: gh release create vX.Y.Z in the public repo to trigger PyPI/MCP-Registry publish