recipe-maintainer/.claude/commands/recipe-upgrade-apply.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Execute a planned recipe upgrade — apply changes, deploy, test, commit/tag	<recipe-name>	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 <DOMAIN> --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://<DOMAIN> 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-<YYYY-MM-DD>.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 <service> to <new-tag>". 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):

      Upgrade `<recipe>` image tags (current recipe version `<current-version>`).
      
      ## Image tag changes
      
      | Service | Old tag | New tag |
      |---------|---------|---------|
      | app | 1.0.0 | 1.1.0 |
      
      ## Upstream release notes
      
      **<service> <old>→<new>:** <url>
      <!-- one line per upgraded image/service; pull each URL from recipe-info/<recipe>/upstream.md
           (between the current → new version). These links MUST be in the PR body itself, not just
           the report — so a reviewer sees exactly what changed upstream. -->
      
      ## Test results
      
      | Test | Result |
      |------|--------|
      | `tests/test_foo.py` | ✓ PASS |
      | URL `https://<domain>` | ✓ 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 <recipe> -<x|y|z>
      
      <!-- pick -x major / -y minor / -z patch per the upgrade; /recipe-upstream reads this line. -->
      
      ## Next steps (after PR review)
      
      ```bash
      # 1. Review the PR on git.autonomic.zone:
      #    <gitea-pr-url>
      
      # 2. Pull the PR branch to your local dev machine:
      cd ~/.abra/recipes/<recipe>
      git fetch git@git.autonomic.zone:recipe-maintainers/<recipe>.git <branch>:<branch>
      git checkout <branch>
      
      # 3. Push to your upstream fork:
      git push dev HEAD:<branch>
      
      # 4. Open a PR on upstream and merge it:
      #    https://git.coopcloud.tech/coop-cloud/<recipe>/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 <recipe> -<x|y|z>
      

    • 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 <gitea-pr-url>, <branch>, the release flag -<x|y|z>, and $ARGUMENTS:

      # 1. Review the PR on git.autonomic.zone:
      #    <gitea-pr-url>
      
      # 2. Pull the PR branch to your local dev machine:
      cd ~/.abra/recipes/$ARGUMENTS
      git fetch git@git.autonomic.zone:recipe-maintainers/$ARGUMENTS.git <branch>:<branch>
      git checkout <branch>
      
      # 3. Push to your upstream fork:
      git push dev HEAD:<branch>
      
      # 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 -<x|y|z>