/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