| 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:
pyproject.toml — project.version (the source of truth).claude-plugin/plugin.json — version.claude-plugin/marketplace.json — plugins[0].versiongemini-extension.json — versionfuturesearch-mcp/pyproject.toml — project.version AND dependencies (futuresearch>=X.Y.Z)futuresearch-mcp/server.json — version AND packages[0].versionfuturesearch-mcp/manifest.json — versionCITATION.cff — version AND date-released (set to today's date)README.md — BibTeX version field in the citation blockstubs/everyrow/pyproject.toml — project.version AND dependencies (futuresearch>=X.Y.Z)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:
-
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').
-
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
-
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)
-
Watch the run:
gh run list --repo futuresearch/futuresearch-python --workflow=publish.yaml --limit 1
Checklist
