upstream-release

name	upstream-release
description	Handle upstream-release issues — read changelog deltas, update spec docs, sync protocol and gateway types, run tests, open PR, tag release
license	MIT
metadata	{"audience":"maintainers","workflow":"github"}

What I do

Automate the full upstream release sync workflow for openclaw-go when a new OpenClaw gateway version is published.

When to use me

Use this skill when handling GitHub issues labeled upstream-release or when a new OpenClaw gateway version needs to be synced into this library.

Workflow

1. Read the issue — extract the changelog excerpt and identify API/protocol deltas (new RPCs, changed params, removed fields, new event types).

2. Create or update the spec doc — write docs/specs/<version>.md summarizing upstream deltas and required work items.

3. Update protocol types — add or modify types in protocol/ to match the upstream wire format:

   • New *Params and *Result structs
   • New constants (methods, event names, scopes)
   • Updated json tags and field types
   • Run go vet ./protocol/... after changes

4. Update gateway methods — add typed convenience methods in gateway/methods.go:

   • Follow the existing pattern: marshal params → client.Send() → unmarshal result
   • Method name matches the RPC name in PascalCase
   • Include GoDoc comment referencing the RPC method string

5. Update tests — add test cases in gateway/methods_test.go:

   • Follow existing table-driven test pattern
   • Mock the expected request/response exchange
   • Cover both success and error paths

6. Update CHANGELOG.md — add entries under [Unreleased] > Added following Keep a Changelog format.

7. Update docs-site package pages — add new methods to docs-site/packages/gateway.md and any new types to docs-site/packages/protocol.md.

8. Run validation:

   go test ./... -race
   go vet ./...
   

9. Complete review gates before marking the PR ready:

   • Architecture review — confirm type design matches upstream semantics
   • Go standards review — idiomatic naming, error handling, documentation
   • API coverage review — every new upstream RPC has a typed method and test
   • Security review — no credential leaks, safe defaults

10. Open PR to main with:

    • Summary of upstream changes
    • Link to the upstream-release issue
    • Test results pasted in the PR body

11. After PR merge only — create tag and GitHub release:

    git tag v<version>
    gh release create v<version> --title "v<version>" --notes "..."
    

12. Close the issue with a link to the release.

Key files

• protocol/types.go — wire types
• protocol/constants.go — method strings, scopes, roles
• gateway/methods.go — typed RPC methods
• gateway/methods_test.go — method tests
• CHANGELOG.md — release notes
• docs/specs/ — version spec documents
• docs-site/packages/ — published package docs

Rules

• Never push directly to main — always use feature branches and PRs.
• Branch naming: issue/<number>-upstream-release-v<version>
• One upstream version per PR — do not batch multiple releases.
• Every new RPC must have a typed method, a test, a CHANGELOG entry, and a docs update.