feat(scripts): add automated version bump script with optional push flag

[Edison-A-N]

Add Version Bump Script

📋 Summary

This PR introduces an automated version bumping script (scripts/bump_version.py) to streamline the release workflow, replacing manual version updates in pyproject.toml and src/openagents/__init__.py.

✨ Features

Version Bump Types

The script supports all semantic versioning bump types:

Type	Example	Use Case
major	0.8.5 → 1.0.0	Breaking changes
minor	0.8.5 → 0.9.0	New features (backward compatible)
patch	0.8.5 → 0.8.6	Bug fixes
post	0.8.5 → 0.8.5.post1	Hotfixes and minor updates

What the Script Does

1. ✅ Reads current version from pyproject.toml
2. ✅ Calculates new version based on bump type
3. ✅ Updates both pyproject.toml and src/openagents/__init__.py
4. ✅ Creates a git commit with conventional message format
5. ✅ Creates a git tag (format: vX.Y.Z)
6. ✅ Optionally pushes changes and tag to remote (with --push flag)

🚀 Usage

Basic Usage (Local Only)

python3 scripts/bump_version.py patch
python3 scripts/bump_version.py minor
python3 scripts/bump_version.py major
python3 scripts/bump_version.py post

This creates a commit and tag locally without pushing to remote.

Push to Remote

python3 scripts/bump_version.py patch --push

This pushes the commit and tag to remote, ready for release.

🔒 Design Decisions

1. --push Flag as Safety Guard

The --push parameter is implemented as an opt-in safety feature:

Current Design (with --push):

• ✅ Prevents accidental pushes during testing
• ✅ Allows local verification before pushing
• ✅ Suitable for contributors and multi-maintainer workflows

Alternative (without --push):
If the release process is exclusively managed by core maintainers, the --push flag can be removed to simplify the workflow. This would make the script always push by default, reducing command verbosity for trusted release managers.

Recommendation: Keep the --push flag for now to provide flexibility and safety. It can be removed in a future iteration if the team prefers a simpler workflow.

2. GitHub Release Creation

The current implementation does not automatically create GitHub Releases. Instead, it provides a URL for manual release creation.

Why not automated?

• Allows manual review and editing of release notes
• Avoids dependency on gh CLI tool
• Separates version management from release publishing

How to add GitHub Release automation:

If desired, add the following code to the script (after line 156, in the if push: block) and install gh CLI:

# Create GitHub release using gh CLI
print("\nCreating GitHub release...")
run_command(
    f'gh release create v{new_version} --title "Release {new_version}" --generate-notes'
)
print(f"✓ Created GitHub release v{new_version}")

Prerequisites:

# Install GitHub CLI
brew install gh  # macOS
# or: sudo apt install gh  # Linux

# Authenticate
gh auth login

This will automatically create a GitHub release with auto-generated release notes.

🔄 Future Enhancement: CI/CD Integration

Recommended: PyPI Publishing via GitHub Actions

To fully automate the release process, a GitHub Actions workflow can be added that triggers on new version tags (e.g., v*), builds the package, and publishes to PyPI automatically. This would enable:

• ✅ Fully automated release pipeline
• ✅ Consistent release process
• ✅ Reduced human error
• ✅ Immediate PyPI availability after version bump

🧪 Testing

All version bump types have been tested:

• ✅ post: 0.8.5.post2 → 0.8.5.post3
• ✅ patch: 0.8.5.post2 → 0.8.6
• ✅ minor: 0.8.5.post2 → 0.9.0
• ✅ major: 0.8.5.post2 → 1.0.0

All test commits have been cleaned up and permanently removed from git history.

📝 Example Workflow

Option 1: Direct Push (Recommended for maintainers)

# One-step: create, commit, tag, and push
python3 scripts/bump_version.py minor --push

# Then create GitHub Release
# - Manual: Visit the provided URL in the output
# - With gh CLI: gh release create vX.Y.Z --generate-notes
# - With GitHub Actions: Automatically triggered on tag push (if configured)

Option 2: Verify Before Push (Safer)

# Step 1: Create version bump locally
python3 scripts/bump_version.py minor

# Step 2: Verify changes
git show HEAD
git diff HEAD~1

# Step 3: Push to remote
git push && git push --tags

# Step 4: Create GitHub Release
# - Manual: Visit https://github.com/bestagents/openagents/releases/new?tag=vX.Y.Z
# - With gh CLI: gh release create vX.Y.Z --generate-notes
# - With GitHub Actions: Automatically triggered on tag push (if configured)

🔗 Reference

This script is inspired by mcpadapt's bump_version.py, adapted for OpenAgents' specific project structure and workflow.

🤔 Questions for Review

1. Should we remove the --push flag for a simpler workflow?
2. Should we enable automatic GitHub Release creation (requires gh CLI)?
3. Should we implement the PyPI publishing workflow in this PR or a follow-up?

---

Closes: N/A
Related: Release automation discussion

[vercel]

@Edison-A-N is attempting to deploy a commit to the Raphael's projects Team on Vercel.

A member of the Team first needs to authorize it.