π OpenHands: AI-Driven Development
feat: add release skill and create-release workflow (#900)
Rohit Malhotrab7e5882b767c
diff --git a/.agents/skills/release.md b/.agents/skills/release.mdnew file mode 100644index 0000000000..b478be04e0--- /dev/null+++ b/.agents/skills/release.md@@ -0,0 +1,191 @@+---+name: release+description: Guide the release process for @openhands/agent-canvas β version bump PR, E2E validation, merge with automatic tagging, and downstream npm/Docker publishing.+triggers:+- release+- new release+- cut a release+- publish release+- bump version+---++# Release Process for @openhands/agent-canvas++You are guiding a release of the `@openhands/agent-canvas` package. Follow these steps **in order**. Do NOT skip ahead β each step has a checkpoint where you must wait for the user.++## Step 1: Check Current Version and Ask the User++**IMPORTANT: You MUST complete this step and get explicit user confirmation before doing anything else.**++First, read the current version from `package.json`:++```bash+node -p "require('./package.json').version"+```++Then present the result to the user and suggest the next logical version. Use these rules to form your suggestion:+- If the current version is a pre-release like `1.0.0-alpha.7`, suggest `1.0.0-alpha.8` (bump the last numeric segment).+- If the current version is stable like `1.2.3`, suggest `1.2.4` (patch bump) but mention they can also do `1.3.0` (minor) or `2.0.0` (major).++**Version format**: This project uses semver with optional pre-release suffixes.+- Pre-release examples: `1.0.0-alpha.8`, `1.0.0-beta.1`, `1.0.0-rc.1`+- Stable examples: `1.0.0`, `1.1.0`, `2.0.0`++**STOP HERE.** Tell the user the current version, your suggested next version, and ask:++> The current version is `<current>`. I'd suggest bumping to `<suggested>`. What version would you like to release?++**Do not proceed to Step 2 until the user confirms a version.**++## Step 2: Create the Release PR++### 2a. Create the release branch++The branch **must** be named `rel-<version>` (e.g., `rel-1.0.0-alpha.8`). This naming convention is required β the `create-release.yml` workflow detects merged release PRs by matching the `rel-` branch prefix.++```bash+git checkout main+git pull origin main+git checkout -b rel-<version>+```++### 2b. Bump the version++Update the version in **both** `package.json` and `package-lock.json`:++```bash+npm version <version> --no-git-tag-version+```++This updates both files without creating a git tag (the tag is created automatically on merge).++Verify the change:++```bash+git diff --stat+# Should show: package.json and package-lock.json changed+```++### 2c. Commit and push++```bash+git add package.json package-lock.json+git commit -m "chore: bump version to <version>"+git push -u origin rel-<version>+```++### 2d. Create the PR++Create the PR targeting `main` with the `e2e-tests` label:++```bash+gh pr create \+ --title "chore: bump version to <version>" \+ --body "## Release v<version>++This PR bumps the version to **<version>** for release.++### Release Checklist+- [x] Version bumped in package.json and package-lock.json+- [ ] CI passes (lint, test, build)+- [ ] Visual snapshot tests pass+- [ ] Mock-LLM E2E tests pass (triggered by \`e2e-tests\` label)+- [ ] Review and approve++### What happens on merge+When this PR is merged, the \`create-release.yml\` workflow will automatically:+1. Create a GitHub release with tag \`v<version>\` and auto-generated notes+2. The tag push triggers \`npm-publish.yml\` to publish to npm+3. The tag push triggers \`docker.yml\` to build and push Docker images to GHCR" \+ --base main \+ --head "rel-<version>" \+ --label "e2e-tests"+```++## Step 3: Wait for CI and E2E Tests++The following checks must pass before merging:++| Workflow | Trigger | What it checks |+|---|---|---|+| **CI** (`ci.yml`) | Every PR | Lint, unit tests, app build, library build |+| **Snapshot Tests** (`snapshot-tests.yml`) | Every PR | Visual regression screenshots |+| **Mock-LLM E2E Tests** (`mock-llm-e2e.yml`) | `e2e-tests` label | End-to-end tests with a mock LLM against a real agent-server |++Monitor the PR checks:++```bash+gh pr checks <pr-number> --watch+```++If the mock-LLM E2E tests fail, investigate the failure in the workflow artifacts. The `e2e-tests` label can be removed and re-added to re-trigger the workflow.++If snapshot tests show intentional changes (e.g., version string in the UI changed), add the `update-snapshots` label to acknowledge the changes.++## Step 4: Merge the PR++Once all checks pass and the PR is approved, merge it:++```bash+gh pr merge <pr-number> --squash --delete-branch+```++### Automatic tagging on merge++The `create-release.yml` workflow automatically runs when a PR from a `rel-*` branch is merged into `main`. It will:++1. **Extract the version** from the branch name (e.g., `rel-1.0.0-alpha.8` β `1.0.0-alpha.8`)+2. **Create a GitHub release** with tag `v<version>` targeting the merge commit+3. **Auto-generate release notes** from the commits since the previous release+4. **Mark pre-release versions** (those containing a hyphen) as pre-releases++You do **not** need to manually create a tag or GitHub release.++### Downstream workflows triggered by the tag++The tag push (`v*`) automatically triggers:++| Workflow | What it does |+|---|---|+| **npm-publish.yml** | Builds and publishes `@openhands/agent-canvas` to npm with provenance |+| **docker.yml** | Builds and pushes multi-arch Docker images to `ghcr.io/openhands/agent-canvas` |++### Verify the release++After merging, verify the downstream workflows complete successfully:++```bash+# Check the GitHub release was created+gh release view v<version>++# Watch downstream workflow runs+gh run list --workflow=npm-publish.yml --limit=1+gh run list --workflow=docker.yml --limit=1+```++Confirm the package is available:+- **npm**: `npm view @openhands/agent-canvas@<version>`+- **Docker**: `docker pull ghcr.io/openhands/agent-canvas:<version>`++## Troubleshooting++### E2E tests not triggering+The `e2e-tests` label must be present on the PR. If you added it but tests didn't run, remove and re-add the label, or manually trigger the workflow from the Actions tab.++### Tag already exists+If a tag `v<version>` already exists (e.g., from a previous failed attempt), the `create-release.yml` workflow will skip creation. Delete the existing release and tag first:+```bash+gh release delete v<version> --yes+git push origin :refs/tags/v<version>+```++### npm publish failed+The `npm-publish.yml` workflow validates that `package.json` version matches the tag version. If they don't match, the publish will fail. Ensure the version bump in Step 2b matches the branch name exactly.++## Reference++This release process is modeled after the [OpenHands/software-agent-sdk release workflow](https://github.com/OpenHands/software-agent-sdk/blob/main/.github/workflows/README-RELEASE.md) for consistency across OpenHands projects. Key differences:+- agent-canvas uses npm (not PyPI) for package publishing+- agent-canvas uses `npm version` (not `make set-package-version`) for version bumping+- agent-canvas release branches use `rel-<version>` naming (same as SDK)+- Both repos use `create-release.yml` to auto-create GitHub releases on merge of `rel-*` PRsdiff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.ymlnew file mode 100644index 0000000000..9d6d82ac35--- /dev/null+++ b/.github/workflows/create-release.yml@@ -0,0 +1,111 @@+---+name: Create GitHub Release++# Automatically create a GitHub release when a release PR is merged into main.+# This bridges the gap between merging the release PR and the downstream+# workflows (npm-publish, docker) which trigger on tag push (v*).+#+# Modeled after OpenHands/software-agent-sdk's create-release.yml for consistency.++on:+ pull_request:+ types: [closed]+ branches: [main]++jobs:+ create-release:+ # Only run when a release PR is merged (not just closed)+ # and the branch follows the rel-X.Y.Z naming convention.+ if: >+ github.event.pull_request.merged == true &&+ startsWith(github.event.pull_request.head.ref, 'rel-')+ runs-on: ubuntu-24.04+ permissions:+ contents: write+ pull-requests: read+ steps:+ - name: Extract version from branch name+ id: version+ env:+ PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}+ run: |+ BRANCH="$PR_HEAD_REF"+ VERSION="${BRANCH#rel-}"++ # Accept semver with optional pre-release suffix (e.g. 1.0.0, 1.0.0-alpha.8)+ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$ ]]; then+ echo "β Could not extract valid version from branch: $BRANCH"+ exit 1+ fi++ echo "version=$VERSION" >> "$GITHUB_OUTPUT"+ echo "π¦ Version: $VERSION"++ - name: Check release does not already exist+ id: check+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ VERSION: ${{ steps.version.outputs.version }}+ run: |+ if gh release view "v${VERSION}" --repo "${{ github.repository }}" > /dev/null 2>&1; then+ echo "β οΈ Release v${VERSION} already exists, skipping"+ echo "exists=true" >> "$GITHUB_OUTPUT"+ else+ echo "exists=false" >> "$GITHUB_OUTPUT"+ fi++ - name: Find previous release tag+ if: steps.check.outputs.exists == 'false'+ id: prev_tag+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ run: |+ PREV_TAG=$(gh release list --repo "${{ github.repository }}" \+ --exclude-drafts --limit 1 \+ --json tagName --jq '.[0].tagName')+ echo "prev_tag=${PREV_TAG}" >> "$GITHUB_OUTPUT"+ echo "π Previous release tag: ${PREV_TAG:-<none>}"++ - name: Create GitHub Release+ if: steps.check.outputs.exists == 'false'+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ VERSION: ${{ steps.version.outputs.version }}+ PREV_TAG: ${{ steps.prev_tag.outputs.prev_tag }}+ run: |+ NOTES_START_FLAG=()+ if [ -n "$PREV_TAG" ]; then+ NOTES_START_FLAG=(--notes-start-tag "$PREV_TAG")+ fi++ # Detect pre-release versions (anything with a hyphen, e.g. 1.0.0-alpha.8)+ PRERELEASE_FLAG=()+ if [[ "$VERSION" == *-* ]]; then+ PRERELEASE_FLAG=(--prerelease)+ fi++ gh release create "v${VERSION}" \+ --repo "${{ github.repository }}" \+ --target "${{ github.event.pull_request.merge_commit_sha }}" \+ --title "v${VERSION}" \+ --generate-notes \+ "${NOTES_START_FLAG[@]}" \+ "${PRERELEASE_FLAG[@]}"++ echo "β Release v${VERSION} created!"+ echo "π https://github.com/${{ github.repository }}/releases/tag/v${VERSION}"++ - name: Summary+ if: steps.check.outputs.exists == 'false'+ env:+ VERSION: ${{ steps.version.outputs.version }}+ run: |+ echo "## β Release v${VERSION} Created" >> "$GITHUB_STEP_SUMMARY"+ echo "" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Tag**: v${VERSION}" >> "$GITHUB_STEP_SUMMARY"+ echo "- **Release**: https://github.com/${{ github.repository }}/releases/tag/v${VERSION}" >> "$GITHUB_STEP_SUMMARY"+ echo "" >> "$GITHUB_STEP_SUMMARY"+ echo "### Triggered Downstream Workflows" >> "$GITHUB_STEP_SUMMARY"+ echo "The tag push \`v${VERSION}\` will automatically trigger:" >> "$GITHUB_STEP_SUMMARY"+ echo "- **npm-publish.yml** β publish \`@openhands/agent-canvas\` to npm" >> "$GITHUB_STEP_SUMMARY"+ echo "- **docker.yml** β build and push \`ghcr.io/openhands/agent-canvas\` Docker images" >> "$GITHUB_STEP_SUMMARY"diff --git a/AGENTS.md b/AGENTS.mdindex 5769b73141..abc5f05320 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -528,4 +528,6 @@ When adding code that needs a new string, decide up front which rule it falls un- Spec files live under `specs/`. Spec IDs are stable β never renumber. Mark deprecated specs with ~~strikethrough~~. Tag implementation code and tests with `// @spec BM-002 β Short title` comments so specs are grep-able across the codebase (`grep -rn '@spec BM-' src/ __tests__/`). Place the comment on the line immediately above the relevant code block or test. When multiple tests cover the same spec, use `it.each` if the test structure is identical.+- Release automation: `.github/workflows/create-release.yml` automatically creates a GitHub release (with tag `v<version>`) when a PR from a `rel-*` branch is merged into `main`. This is modeled after the SDK's `create-release.yml`. The tag push then triggers `npm-publish.yml` and `docker.yml` downstream. The release skill (`.agents/skills/release.md`, keyword trigger: `release`) guides agents through the full process: version bump PR, `e2e-tests` label for mock-LLM E2E validation, merge with auto-tagging. Pre-release versions (containing a hyphen) are marked as pre-releases on the GitHub release.+- Cloud conversation resume gating: when a cloud conversation is closed from the UI (`pauseCloudSandbox` is called), the conversation's `conversation_url` is NOT cleared -- it still points to the old sandbox host. `WebSocketProviderWrapper` must suppress the URL (pass `null` to `ConversationWebSocketProvider`) while `sandbox_status === "PAUSED"`, otherwise the WebSocket immediately tries the stale URL before the sandbox wakes. Symmetrically, `useActiveConversation`'s refetch interval must fast-poll (3 s) on both `!conversation_url` AND `sandbox_status === "PAUSED"` -- checking only the missing URL would leave the hook on the 30 s interval while the sandbox is resuming. The resume sequence: navigate -> sandbox PAUSED detected -> `resumeCloudSandbox` called (in `conversation.tsx`) -> fast-poll detects RUNNING -> `conversationUrl` unblocked -> WebSocket connects.