Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: add implementation plan for version bump workflows

Claude2aed5e6b5993
diff --git a/docs/plans/2025-10-25-version-bump-workflows.md b/docs/plans/2025-10-25-version-bump-workflows.md
new file mode 100644
index 0000000000..92392f9dc7
--- /dev/null
+++ b/docs/plans/2025-10-25-version-bump-workflows.md
@@ -0,0 +1,628 @@
+# Version Bump Workflows Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Replace Makefile-based bump2version commands with GitHub Actions workflow_dispatch workflows accessible via links in Development.md.
+
+**Architecture:** Reusable workflow pattern with one core workflow containing bump2version logic, and 7 caller workflows (one per Python package) that invoke the reusable workflow with package-specific parameters.
+
+**Tech Stack:** GitHub Actions, bump2version, git
+
+---
+
+## Task 1: Create Reusable Workflow
+
+**Files:**
+- Create: `.github/workflows/bump-version-reusable.yml`
+
+**Step 1: Create the reusable workflow file**
+
+Create `.github/workflows/bump-version-reusable.yml`:
+
+```yaml
+name: Bump Version (Reusable)
+
+on:
+ workflow_call:
+ inputs:
+ package_name:
+ description: 'Package display name (e.g., cua-core)'
+ required: true
+ type: string
+ package_directory:
+ description: 'Package directory relative to repo root (e.g., libs/python/core)'
+ required: true
+ type: string
+ bump_type:
+ description: 'Version bump type (patch, minor, or major)'
+ required: true
+ type: string
+
+permissions:
+ contents: write
+
+jobs:
+ bump-version:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ token: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+
+ - name: Install bump2version
+ run: pip install bump2version
+
+ - name: Configure Git
+ run: |
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+
+ - name: Run bump2version
+ run: |
+ cd ${{ inputs.package_directory }}
+ bump2version ${{ inputs.bump_type }}
+
+ - name: Push changes
+ run: |
+ git push origin main --follow-tags
+```
+
+**Step 2: Validate YAML syntax**
+
+Run: `yamllint .github/workflows/bump-version-reusable.yml` (if available) or use online validator
+
+Expected: No syntax errors
+
+**Step 3: Verify structure**
+
+Check that:
+- File has correct `workflow_call` trigger
+- All 3 inputs are defined (package_name, package_directory, bump_type)
+- Permissions include `contents: write`
+- Steps follow correct order: checkout → setup → install → git config → bump → push
+
+**Step 4: Commit**
+
+```bash
+git add .github/workflows/bump-version-reusable.yml
+git commit -m "feat: add reusable bump version workflow"
+```
+
+---
+
+## Task 2: Create Caller Workflow for cua-core
+
+**Files:**
+- Create: `.github/workflows/bump-version-core.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-core.yml`:
+
+```yaml
+name: Bump cua-core Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-core'
+ package_directory: 'libs/python/core'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate YAML syntax**
+
+Run: Check syntax with validator
+
+Expected: No syntax errors
+
+**Step 3: Verify structure**
+
+Check that:
+- File has `workflow_dispatch` trigger with bump_type input
+- Input type is `choice` with options: patch, minor, major
+- Job calls reusable workflow with correct path
+- Package-specific values are correct: 'cua-core' and 'libs/python/core'
+- `secrets: inherit` is present
+
+**Step 4: Commit**
+
+```bash
+git add .github/workflows/bump-version-core.yml
+git commit -m "feat: add bump version workflow for cua-core"
+```
+
+---
+
+## Task 3: Create Caller Workflow for cua-computer
+
+**Files:**
+- Create: `.github/workflows/bump-version-computer.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-computer.yml`:
+
+```yaml
+name: Bump cua-computer Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-computer'
+ package_directory: 'libs/python/computer'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure (same as Task 2)
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-computer.yml
+git commit -m "feat: add bump version workflow for cua-computer"
+```
+
+---
+
+## Task 4: Create Caller Workflow for cua-agent
+
+**Files:**
+- Create: `.github/workflows/bump-version-agent.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-agent.yml`:
+
+```yaml
+name: Bump cua-agent Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-agent'
+ package_directory: 'libs/python/agent'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-agent.yml
+git commit -m "feat: add bump version workflow for cua-agent"
+```
+
+---
+
+## Task 5: Create Caller Workflow for cua-som
+
+**Files:**
+- Create: `.github/workflows/bump-version-som.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-som.yml`:
+
+```yaml
+name: Bump cua-som Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-som'
+ package_directory: 'libs/python/som'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-som.yml
+git commit -m "feat: add bump version workflow for cua-som"
+```
+
+---
+
+## Task 6: Create Caller Workflow for pylume
+
+**Files:**
+- Create: `.github/workflows/bump-version-pylume.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-pylume.yml`:
+
+```yaml
+name: Bump pylume Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'pylume'
+ package_directory: 'libs/python/pylume'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-pylume.yml
+git commit -m "feat: add bump version workflow for pylume"
+```
+
+---
+
+## Task 7: Create Caller Workflow for cua-computer-server
+
+**Files:**
+- Create: `.github/workflows/bump-version-computer-server.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-computer-server.yml`:
+
+```yaml
+name: Bump cua-computer-server Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-computer-server'
+ package_directory: 'libs/python/computer-server'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-computer-server.yml
+git commit -m "feat: add bump version workflow for cua-computer-server"
+```
+
+---
+
+## Task 8: Create Caller Workflow for cua-mcp-server
+
+**Files:**
+- Create: `.github/workflows/bump-version-mcp-server.yml`
+
+**Step 1: Create the caller workflow file**
+
+Create `.github/workflows/bump-version-mcp-server.yml`:
+
+```yaml
+name: Bump cua-mcp-server Version
+
+on:
+ workflow_dispatch:
+ inputs:
+ bump_type:
+ description: 'Version bump type'
+ required: true
+ type: choice
+ options:
+ - patch
+ - minor
+ - major
+
+jobs:
+ bump:
+ uses: ./.github/workflows/bump-version-reusable.yml
+ with:
+ package_name: 'cua-mcp-server'
+ package_directory: 'libs/python/mcp-server'
+ bump_type: ${{ inputs.bump_type }}
+ secrets: inherit
+```
+
+**Step 2: Validate and verify**
+
+Check syntax and structure
+
+**Step 3: Commit**
+
+```bash
+git add .github/workflows/bump-version-mcp-server.yml
+git commit -m "feat: add bump version workflow for cua-mcp-server"
+```
+
+---
+
+## Task 9: Update Development.md
+
+**Files:**
+- Modify: `Development.md` (replace "Releasing Packages" section)
+
+**Step 1: Read the current Development.md**
+
+Run: `cat Development.md | grep -A 50 "## Releasing Packages"`
+
+Expected: See current content about Makefile and bump2version
+
+**Step 2: Replace the "Releasing Packages" section**
+
+Replace the entire "Releasing Packages" section (starting at line ~350) with:
+
+```markdown
+## Releasing Packages
+
+Cua uses automated GitHub Actions workflows to bump package versions. Click the links below to trigger a version bump:
+
+> **Note:** The main branch is currently not protected. If branch protection is enabled in the future, the github-actions bot must be added to the bypass list for these workflows to commit directly.
+
+### Version Bump Workflows
+
+| Package | Workflow Link |
+|---------|---------------|
+| **cua-core** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-core.yml) |
+| **cua-computer** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-computer.yml) |
+| **cua-agent** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-agent.yml) |
+| **cua-som** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-som.yml) |
+| **pylume** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-pylume.yml) |
+| **cua-computer-server** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-computer-server.yml) |
+| **cua-mcp-server** | [Bump Version](https://github.com/trycua/cua/actions/workflows/bump-version-mcp-server.yml) |
+
+**How to use:**
+1. Click the workflow link for the package you want to bump
+2. Click the "Run workflow" button in the GitHub UI
+3. Select the bump type from the dropdown (patch/minor/major)
+4. Click "Run workflow" to start the version bump
+5. The workflow will automatically commit changes and push to main
+
+### Rolling Back a Version Bump
+
+If you need to revert a version bump, follow these steps:
+
+**Step 1: Find the version bump commit**
+
+```bash
+# List recent commits
+git log --oneline | grep "Bump"
+
+# Example output:
+# a1b2c3d Bump version: 0.1.8 → 0.1.9
+```
+
+**Step 2: Revert the commit**
+
+```bash
+# Revert the specific commit
+git revert <commit-hash>
+
+# Example:
+# git revert a1b2c3d
+```
+
+**Step 3: Delete the git tag**
+
+```bash
+# List tags to find the version tag
+git tag -l
+
+# Delete the tag locally
+git tag -d v0.1.9
+
+# Delete the tag remotely
+git push origin :refs/tags/v0.1.9
+```
+
+**Step 4: Push the revert**
+
+```bash
+git push origin main
+```
+
+**Per-package tag patterns:**
+- All packages use tags like `v{version}` (e.g., `v0.1.9`, `v1.0.0`)
+- Each package's .bumpversion.cfg defines the exact tag format
+
+### Local Testing (Advanced)
+
+The Makefile targets are kept for local testing only:
+
+```bash
+# Test version bump locally (dry run)
+make dry-run-patch-core
+
+# View current versions
+make show-versions
+```
+
+**Note:** For production releases, always use the GitHub Actions workflows above instead of running Makefile commands directly.
+```
+
+**Step 3: Verify the changes**
+
+Run: `grep -A 5 "## Releasing Packages" Development.md`
+
+Expected: See new content with workflow links table
+
+**Step 4: Commit**
+
+```bash
+git add Development.md
+git commit -m "docs: update Development.md with version bump workflow links"
+```
+
+---
+
+## Task 10: Add Note to Makefile (Optional)
+
+**Files:**
+- Modify: `Makefile`
+
+**Step 1: Add deprecation note at the top of version bump section**
+
+Find the version bump targets section in Makefile and add this comment at the top:
+
+```makefile
+# NOTE: For production releases, prefer using GitHub Actions workflows (see Development.md)
+# These targets are kept for local testing and dry-runs only.
+```
+
+**Step 2: Commit**
+
+```bash
+git add Makefile
+git commit -m "docs: add note to Makefile about preferring workflows"
+```
+
+---
+
+## Verification Steps
+
+After completing all tasks, verify the implementation:
+
+**1. Check all workflow files exist:**
+
+```bash
+ls -la .github/workflows/bump-version*.yml
+```
+
+Expected: 8 files (1 reusable + 7 caller workflows)
+
+**2. Verify Development.md has links:**
+
+```bash
+grep "bump-version-core.yml" Development.md
+```
+
+Expected: Link to workflow found
+
+**3. Test one workflow manually:**
+
+- Navigate to: https://github.com/trycua/cua/actions/workflows/bump-version-core.yml
+- Click "Run workflow"
+- Select "patch"
+- Click "Run workflow"
+- Verify it runs successfully and creates a commit + tag
+
+**4. Final commit and push:**
+
+```bash
+git status
+git push origin feature/version-bump-workflows
+```
+
+---
+
+## Success Criteria
+
+- ✅ 1 reusable workflow file created
+- ✅ 7 caller workflow files created (one per package)
+- ✅ Development.md updated with workflow links table
+- ✅ Development.md includes branch protection note
+- ✅ Development.md includes rollback instructions
+- ✅ Makefile includes deprecation note
+- ✅ All changes committed with clear commit messages
+- ✅ Manual test of at least one workflow succeeds