diff --git a/.agents/skills/bumping-web/SKILL.md b/.agents/skills/bumping-web/SKILL.md new file mode 100644 index 0000000000..959fdad4e8 --- /dev/null +++ b/.agents/skills/bumping-web/SKILL.md @@ -0,0 +1,118 @@ +--- +name: bumping-web +description: Use when the user asks to bump, update, or upgrade the OpenCloud web assets/frontend to a specific version (e.g. "bump web to v7.0.0", "update web to v7.1.2"). Covers editing the version files, the single commit, and opening the PR against the right branch. +--- + +# Bumping Web + +## Overview + +Bumping web updates the pinned OpenCloud web frontend (assets + UI-test runner) to a tagged release of [opencloud-eu/web](https://github.com/opencloud-eu/web). It touches exactly two files, lands as one commit, and ships as a PR whose body is the web changelog for that version. + +Template PR: https://github.com/opencloud-eu/opencloud/pull/2733 + +## Prerequisites + +- **`gh` (GitHub CLI), authenticated** — every lookup and the PR creation go through `gh api` / `gh pr`. Verify with `gh auth status`; if it fails, ask the user to run `gh auth login` (suggest `! gh auth login` so it runs in-session). Do not proceed without it. +- `gh` needs the system keyring, so run all `gh` commands with the sandbox disabled. +- `git` and `base64` (decoding the changelog) — standard on macOS/Linux. + +## What changes (exactly two files) + +| File | Variable | New value | +| ----------------------- | -------------------- | ------------------------------------------------ | +| `services/web/Makefile` | `WEB_ASSETS_VERSION` | the version tag, e.g. `v7.0.0` | +| `services/web/Makefile` | `WEB_ASSETS_BRANCH` | branch carrying the tag (`main` or `stable-X.Y`) | +| `.woodpecker.env` | `WEB_COMMITID` | full commit sha the tag points to | +| `.woodpecker.env` | `WEB_BRANCH` | same branch as `WEB_ASSETS_BRANCH` | + +`WEB_ASSETS_BRANCH` and `WEB_BRANCH` are always the same value. + +## Procedure + +Let `VERSION` be the requested tag (always normalize to a leading `v`, e.g. `v7.0.0`). + +### 1. Resolve the commit sha the tag points to + +```bash +gh api repos/opencloud-eu/web/commits/$VERSION --jq '.sha' +``` + +This full sha is the new `WEB_COMMITID`. + +### 2. Determine the branch (`main` vs `stable-X.Y`) + +The branch is the line of development that carries the tag. Detect it: + +```bash +gh api "repos/opencloud-eu/web/compare/main...$VERSION" --jq '.status' +``` + +- `identical` or `behind` → the tagged commit is reachable from `main` → use **`main`**. +- `ahead` or `diverged` → the tag lives on a release line → use **`stable-X.Y`** matching the version's major.minor (e.g. `v7.1.2` → `stable-7.1`). + +Sanity-check that the stable branch actually exists: + +```bash +gh api repos/opencloud-eu/web/branches --paginate --jq '.[].name' | grep -E 'main|stable' +``` + +Typically a freshly released minor (`v7.1.0`) still sits on `main`, while later patches on an older line (`v7.0.3` after `7.1` exists) sit on `stable-7.0`. + +### 3. Fetch the changelog for the PR body + +```bash +gh api "repos/opencloud-eu/web/contents/CHANGELOG.md?ref=$VERSION" --jq '.content' | base64 -d +``` + +Take **only the section for this version**. Match the template: start the PR body at the first content heading (e.g. `### 💥 Breaking changes` / `### 📈 Enhancement`) and drop the `# Changelog` title, the `## [x.y.z] - date` header, and the `### ❤️ Thanks to all contributors!` block. Stop before the next `## [...]` version header. + +### 4. Apply the edits + +Edit `services/web/Makefile` (`WEB_ASSETS_VERSION`, `WEB_ASSETS_BRANCH`) and `.woodpecker.env` (`WEB_COMMITID`, `WEB_BRANCH`). + +### 5. Pick the target branch for the PR + +- Major or minor release → target **`main`**. +- Patch release → may need to target a stable branch instead. If the user did not specify, **ask them** which branch to target before continuing. + +### 6. Confirm before committing + +Show the user the diff of both files and the target branch, and ask them to confirm. Do not commit until they approve. + +### 7. Commit, push, open PR + +- Create a branch (do not commit on `main`). +- One commit, conventional-commits format, **empty body**: + ``` + chore: bump web to v7.0.0 + ``` +- PR title: `[full-ci] chore: bump web to v7.0.0` (the commit message prefixed with `[full-ci] `). +- PR base: the branch chosen in step 5. +- PR body: the trimmed changelog from step 3. +- Add the label `Type:Dependencies`. + +```bash +gh pr create --base \ + --title "[full-ci] chore: bump web to $VERSION" \ + --label "Type:Dependencies" \ + --body-file +``` + +(`gh` commands need the sandbox disabled — they require the system keyring.) + +## Quick reference + +```bash +VERSION=v7.0.0 +gh api repos/opencloud-eu/web/commits/$VERSION --jq '.sha' # WEB_COMMITID +gh api "repos/opencloud-eu/web/compare/main...$VERSION" --jq '.status' # main vs stable +gh api "repos/opencloud-eu/web/contents/CHANGELOG.md?ref=$VERSION" --jq '.content' | base64 -d # changelog +``` + +## Common mistakes + +- Reading `WEB_COMMITID` or the changelog from web `main` instead of from the version tag (`?ref=$VERSION`). Always pin to the tag. +- Leaving `WEB_ASSETS_BRANCH`/`WEB_BRANCH` on `main` for a patch that belongs on a stable line. +- Forgetting `[full-ci] ` in the PR title or adding a commit body. +- Committing before the user confirms the diff and target branch. diff --git a/.claude/skills b/.claude/skills new file mode 120000 index 0000000000..2b7a412b8f --- /dev/null +++ b/.claude/skills @@ -0,0 +1 @@ +../.agents/skills \ No newline at end of file