--- description: Execute a planned recipe upgrade — apply changes, deploy, test, commit/tag argument-hint: allowed-tools: [Bash, Read, Write, Glob, Grep, WebFetch, WebSearch] --- # Recipe Upgrade Apply Execute a previously planned upgrade for a Co-op Cloud recipe. Reads the plan file, applies the changes, deploys to the test instance, runs tests, and commits/tags if everything passes. The recipe name is: $ARGUMENTS Read and follow the instructions in `.claude/commands/includes/logging.md`. Read and follow the instructions in `.claude/commands/includes/guidelines.md`. ## Steps 1. **Get the domain and server for this recipe**: ``` python3 scripts/get_test_instance.py --recipe $ARGUMENTS ``` This outputs DOMAIN and SERVER for the active instance. - If the recipe has no `recipe-info/$ARGUMENTS/recipe.toml`, tell the user to run `/recipe-init $ARGUMENTS` first and stop. 2. **Find and read the upgrade plan** — look for the most recent plan file matching `plans/$ARGUMENTS-upgrade-*.md`. - If no plan file exists, tell the user to run `/recipe-upgrade-plan $ARGUMENTS` first and stop. - Read the plan file to get the image tag changes, version bump, recipe changes, risks, and deployment notes. 3. **Present the plan summary** to the user: - Image tag changes (service / current → new) - Recipe version bump - Risks and caveats - Any post-deploy steps 4. **Apply the upgrades** — update image tags in the local recipe checkout: ``` abra recipe upgrade $ARGUMENTS -n ``` - If the plan specifies manual tag changes (tags that `abra recipe upgrade` won't handle), apply those by editing `~/.abra/recipes/$ARGUMENTS/compose.yml` directly. 5. **Do NOT bump the recipe version label here — record the recommended release bump instead.** The `coop-cloud.${STACK_NAME}.version` label is **not** changed in this PR. The version bump + tag + publish all happen at the very end, after the upstream PR merges, via a single real `abra recipe release` command (see `/recipe-upstream`). All this step does is **decide and record the semver bump** so that command is ready: - Pick the bump from the upgrade's nature per the plan: `-x` (major) for breaking changes, `-y` (minor) for a new feature, `-z` (patch) for a patch/security bump. - Record the recommended release command — `abra recipe release $ARGUMENTS -x|-y|-z` (no `--dry-run`) — for the PR body (step 12). `/recipe-upstream` reads this line back out of the PR to drive the publish. - Leave the version label as-is. (`abra recipe release` at release time computes the final `a.b.c+x.y.z` from the current label + the flag + the app image tag, and syncs the label then.) - Note the current version + the recommended bump for the report. 6. **Apply any additional recipe changes** noted in the plan: - New env vars, changed config templates, new volumes, updated labels, added/removed services, etc. - Only make changes that are documented in the plan file. 7. **Lint the upgraded recipe**: ``` abra recipe lint $ARGUMENTS -C ``` - If lint errors are found, report them and attempt to fix obvious issues. If unfixable, warn the user and continue. 8. **Deploy the upgraded recipe** — follow the same process as `/recipe-deploy $ARGUMENTS`: ``` abra app deploy --chaos --force --no-input ``` - If the plan mentioned post-upgrade migration commands, run them after deployment. 9. **Run the test suite** — follow the same process as `/recipe-test $ARGUMENTS`: - Discover and run all test scripts from `recipe-info/$ARGUMENTS/tests/*.py`. - Read `recipe-info/$ARGUMENTS/test.md` and perform URL-based manual checks using `curl` or `WebFetch`. - If no test directory exists, do a basic health check by curling `https://` and checking for HTTP 200. 10. **Write an upgrade report** for future reference: - Create the `planned-updates/` directory if it doesn't already exist. - Write to `planned-updates/$ARGUMENTS-upgrade-.md` (using today's date). - Include: - Current recipe version + the recommended release bump (e.g. `1.0.2+5.8.3`, bump `-y` minor → published as `abra recipe release` at release time) - Which image tags were upgraded per service - Changelog summary with links to full release notes - Any **Operator Action Required** items - Lint results - Test results (PASS/FAIL for each test) - Any manual steps still needed - Tell the user the file path. 11. **Commit the upgrade** (only if all tests passed): - `cd ~/.abra/recipes/$ARGUMENTS` - Stage the changed files: `git add compose.yml` (and any other modified recipe files). - Commit the image-tag/config changes — e.g. `git commit -m "chore: upgrade to "`. Do **not** mention a recipe version in the message: the version label is not bumped here, and the branch name is derived from the commit (see `/recipe-create-pr`). - Do **NOT** create a tag or bump the version label. The tag + version bump + publish are done at the end by `abra recipe release` (see `/recipe-upstream`), after the upstream PR merges. - If any tests failed, skip this step entirely. 12. **Open a review PR on git.autonomic.zone** (only if step 11 ran): - Before following the `/recipe-create-pr $ARGUMENTS` steps, construct the PR body and export it as `RECIPE_PR_BODY`. Use this format (fill in real values): ```markdown Upgrade `` image tags (current recipe version ``). ## Image tag changes | Service | Old tag | New tag | |---------|---------|---------| | app | 1.0.0 | 1.1.0 | ## Upstream release notes ** →:** ## Test results | Test | Result | |------|--------| | `tests/test_foo.py` | ✓ PASS | | URL `https://` | ✓ PASS | ## Recommended release bump This PR does **not** bump the `coop-cloud.${STACK_NAME}.version` label. After the upstream PR merges, publish the release (which bumps the label + tags + pushes) with: abra recipe release - ## Next steps (after PR review) ```bash # 1. Review the PR on git.autonomic.zone: # # 2. Pull the PR branch to your local dev machine: cd ~/.abra/recipes/ git fetch git@git.autonomic.zone:recipe-maintainers/.git : git checkout # 3. Push to your upstream fork: git push dev HEAD: # 4. Open a PR on upstream and merge it: # https://git.coopcloud.tech/coop-cloud//pulls # 5. After the upstream PR merges, publish the release (bumps the version label, # commits, tags AND pushes the tag — all in one step): abra recipe release - ``` ``` - Then follow the same process as `/recipe-create-pr $ARGUMENTS` (read that skill file). The recipe-create-pr script will use `RECIPE_PR_BODY` as the PR body when that variable is set. - Capture the resulting PR URL — you'll include it in the summary. - If the PR creation fails, do not block: report the error and tell the user they can run `/recipe-create-pr $ARGUMENTS` manually after fixing. 13. **Summarise**: - The current recipe version + the recommended release bump (e.g. `1.0.2+5.8.3`, bump `-y` minor). - Which image tags were upgraded per service (old → new). - Whether the deployment succeeded. - Test results — all passed, or which failed with details. - If any tests failed: highlight failures, suggest troubleshooting, and note the recipe can be rolled back by re-fetching (`abra recipe fetch $ARGUMENTS --force`). - Any manual actions still required (from the plan). - The git.autonomic.zone review PR URL from step 12 (or note that PR creation failed and how to retry). - If all tests passed AND the review PR was opened, give the user these next steps verbatim — substituting ``, ``, the release flag `-`, and `$ARGUMENTS`: ```bash # 1. Review the PR on git.autonomic.zone: # # 2. Pull the PR branch to your local dev machine: cd ~/.abra/recipes/$ARGUMENTS git fetch git@git.autonomic.zone:recipe-maintainers/$ARGUMENTS.git : git checkout # 3. Push to your upstream fork: git push dev HEAD: # 4. Open a PR on upstream and merge it: # https://git.coopcloud.tech/coop-cloud/$ARGUMENTS/pulls # 5. After the upstream PR merges, publish the release (bumps the version label, # commits, tags AND pushes the tag — all in one step): abra recipe release $ARGUMENTS - ```