mirror of
https://github.com/OpenHands/OpenHands.git
synced 2026-10-06 12:33:43 +08:00
4bd3baccde
* ci: adopt release-please via shared release-actions
Standardize agent-canvas releases on the org-wide release-please
automation (OpenHands/release-actions), matching typescript-client and
OpenHands/OpenHands.
Adds the three caller workflows:
- release.yml release-please on push to main / release/**
- pr.yml Conventional-Commit title lint + type: labels
- release-ready.yml draft release PR -> "Ready for review" gate
(Slack alert to #proj-agent-canvas + optional tests)
Adds the release-please state files: release-please-config.json
(node, draft PRs, extra-files), .release-please-manifest.json,
.github/release.yml (changelog categories), version.txt. Manifest is
seeded at 1.0.0 (the current GA release, v1.0.0 shipped 2026-06-15).
extra-files keeps the non-package.json version pins in lockstep:
config/defaults.json ($.versions.agentCanvas) and the README docker
example. The node release-type already bumps package.json and
package-lock.json.
Corrects stale on-main version refs (package.json rc.6,
config/defaults.json + README rc.11) to the real released 1.0.0, so all
pins share a single source of truth.
Removes create-release.yml: release-please now owns tag + GitHub Release
creation. npm-publish.yml and docker.yml are unchanged - they trigger on
the v* tags release-please still produces (pushed with the release App
token so tag-triggered workflows fire).
Co-authored-by: smolpaws <engel@enyst.org>
* fix: sync README.windows.md docker tag + track it in release-please
The docs-version-sync test also checks README.windows.md, which still
pinned 1.0.0-rc.11. Update both its docker image refs to the released
1.0.0 and add it to release-please extra-files (with the
x-release-please-version annotation) so future bumps keep it in lockstep
alongside README.md and config/defaults.json.
Co-authored-by: smolpaws <engel@enyst.org>
* ci: pin v-prefix tagging and first-release start point
Two robustness fixes after confirming agent-canvas's release conventions:
- include-v-in-tag: true (explicit). agent-canvas tags are vX.Y.Z
(v1.0.0, v1.0.0-rc.12), and npm-publish.yml + docker.yml trigger on
push tags 'v*'. release-please's node default already adds the v, but
pin it explicitly so a default change can't silently drop the prefix
and break tag-triggered publishing. (Matches typescript-client, which
also ships v-prefixed tags; differs from OpenHands/OpenHands, which
sets include-v-in-tag:false for its no-v scheme.)
- last-release-sha pinned to the v1.0.0 release commit
(7b9c17e). v1.0.0 is a real, published release (2026-06-15; npm
latest). This tells release-please the first managed release starts
from there, so its first run scans only post-1.0.0 commits instead of
walking the whole history.
Co-authored-by: smolpaws <engel@enyst.org>
* ci: drop orphaned version.txt
Per AI review: version.txt would never be updated and nothing consumes
it. The README's "four state files" guidance assumes the `simple`
release-type (which release-actions itself uses, where version.txt is
the canonical version source). agent-canvas uses `release-type: node`,
where package.json is the source of truth — so version.txt is redundant
and not auto-bumped. The other node adopters (typescript-client,
OpenHands/OpenHands) ship no version.txt either. Remove it rather than
keep a file that silently goes stale.
Co-authored-by: smolpaws <engel@enyst.org>
* docs: document the release-please flow
---------
Co-authored-by: smolpaws <engel@enyst.org>
Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: hieptl <hieptl.developer@gmail.com>
111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
---
|
|
name: release
|
|
description: Guide the release process for @openhands/agent-canvas — review the release-please draft PR, mark it ready, merge it; the tag push publishes to npm and Docker.
|
|
triggers:
|
|
- release
|
|
- new release
|
|
- cut a release
|
|
- publish release
|
|
- bump version
|
|
---
|
|
|
|
# Release Process for @openhands/agent-canvas
|
|
|
|
## Overview
|
|
|
|
Releases are **trunk-based and automated by release-please**, via the shared reusable
|
|
workflows in [`OpenHands/release-actions`](https://github.com/OpenHands/release-actions):
|
|
|
|
1. PRs merge to `main` with **Conventional Commit titles** (`feat`, `fix`, `perf`, `docs`, `chore`, `build`, `ci`, `refactor`, `style`, `test`, `revert`). `.github/workflows/pr.yml` lints the title and applies the matching `type:` label; squash merge uses the PR title as the commit message.
|
|
2. On every push to `main`, `.github/workflows/release.yml` runs release-please, which maintains a **draft release PR** titled `chore(main): release X.Y.Z` accumulating everything merged since the last release.
|
|
3. The release PR pre-stages **every version bump**: `package.json`, `package-lock.json`, `config/defaults.json` (`versions.agentCanvas`), and the Docker image pins in `README.md` / `README.windows.md` (lines annotated with `x-release-please-version`).
|
|
4. Marking the release PR **Ready for review** is the explicit cut-a-release signal: `.github/workflows/release-ready.yml` notifies `#proj-agent-canvas` on Slack and labels the PR `release: ready`.
|
|
5. Merging the release PR makes release-please push the `vX.Y.Z` tag (using the org release App token) and create the GitHub Release. The same tag push triggers `npm-publish.yml` (npm) and `docker.yml` (multi-arch GHCR images).
|
|
|
|
The next version is derived from the conventional-commit types merged since the last release: `fix` → patch, `feat` → minor, any `!` suffix or `BREAKING CHANGE` footer → major. Other types (`docs`, `chore`, `refactor`, …) appear in the release notes but do not by themselves produce a release PR. Release notes are grouped by the `type:` labels via `.github/release.yml`; there is no `CHANGELOG.md` file — GitHub Releases are the changelog.
|
|
|
|
Configuration lives in `release-please-config.json` (version surfaces, draft PR) and `.release-please-manifest.json` (current released version). Maintenance releases for an older line use `release/**` branches (`release.yml` triggers there too).
|
|
|
|
**Never commit to the release PR's branch by hand** — release-please owns it and force-pushes it on every push to `main`.
|
|
|
|
---
|
|
|
|
## Step 1: Find the Release PR
|
|
|
|
```bash
|
|
gh pr list --state open --label "autorelease: pending"
|
|
```
|
|
|
|
If no release PR is open, nothing releasable (`feat`/`fix`/breaking) has merged since the last release — or `release.yml` is failing on `main`:
|
|
|
|
```bash
|
|
gh run list --workflow=release.yml --limit=3
|
|
```
|
|
|
|
---
|
|
|
|
## Step 2: Review It
|
|
|
|
Open the release PR and confirm:
|
|
|
|
- **The version** in the title matches expectations. It is computed from the merged commit types — if it looks wrong, check the conventional types of the PR titles merged since the last release. To force a specific version, merge a commit to `main` whose message contains a `Release-As: X.Y.Z` footer.
|
|
- **The staged bumps** cover all version surfaces (`package.json`, `package-lock.json`, `config/defaults.json`, `README.md`, `README.windows.md`) and the notes list the expected changes.
|
|
|
|
---
|
|
|
|
## Step 3: Cut the Release
|
|
|
|
**STOP HERE and confirm with the user before proceeding.** Marking the PR ready and merging it publishes to npm and GHCR.
|
|
|
|
```bash
|
|
gh pr ready <release-pr-number>
|
|
```
|
|
|
|
This fires the release-ready gate: a Slack notification lands in `#proj-agent-canvas` and the PR is labeled `release: ready`. Then merge the release PR (squash, like any other PR).
|
|
|
|
---
|
|
|
|
## Step 4: Watch the Pipeline
|
|
|
|
Merging the release PR triggers `release.yml` on `main`, which pushes the `vX.Y.Z` tag and creates the GitHub Release; the tag push then fires the publish workflows:
|
|
|
|
```bash
|
|
gh run list --workflow=release.yml --limit=3
|
|
gh run list --workflow=npm-publish.yml --limit=3
|
|
gh run list --workflow=docker.yml --limit=3
|
|
```
|
|
|
|
---
|
|
|
|
## Step 5: Verify the Release
|
|
|
|
```bash
|
|
# GitHub release
|
|
gh release view v<version>
|
|
|
|
# npm (allow ~2 min for publish to propagate)
|
|
npm view @openhands/agent-canvas@<version>
|
|
npm view @openhands/agent-canvas dist-tags # stable releases get `latest`
|
|
|
|
# Docker
|
|
docker pull ghcr.io/openhands/agent-canvas:<version>
|
|
```
|
|
|
|
External install docs on docs.openhands.dev are maintained separately; update them there when closing #1073.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### No release PR appears after merging to main
|
|
Only `feat`, `fix`, and breaking changes produce a release PR. Also check `release.yml` runs on `main` — the workflow fails by design if the org secrets `RELEASE_APP_ID` / `RELEASE_APP_PRIVATE_KEY` are unavailable (a `GITHUB_TOKEN` fallback would create a tag that never triggers the publish workflows).
|
|
|
|
### The proposed version is wrong
|
|
The version comes from the conventional-commit history since the last release. Fix forward: merge a commit to `main` with a `Release-As: X.Y.Z` footer to pin the next version.
|
|
|
|
### No Slack message when the PR was marked ready
|
|
`SLACK_BOT_TOKEN` is optional by design — the gate still applies the `release: ready` label and the release proceeds normally.
|
|
|
|
### package.json version doesn't match the tag
|
|
This cannot happen in the normal flow: release-please bumps `package.json` in the release PR and tags the resulting merge commit, and `npm-publish.yml` validates they match. If it ever fails, someone pushed a tag by hand — delete the tag and let release-please own tagging.
|