--- description: Create a detailed upgrade plan for a recipe argument-hint: allowed-tools: [Bash, Read, Write, Glob, Grep, WebFetch, WebSearch] --- # Recipe Upgrade Plan Research available upgrades for a Co-op Cloud recipe and create a detailed plan file for review before applying. 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. **Fetch the recipe AND pull latest upstream main** — first check for uncommitted local changes: ```bash git -C ~/.abra/recipes/$ARGUMENTS status --short git -C ~/.abra/recipes/$ARGUMENTS diff git -C ~/.abra/recipes/$ARGUMENTS diff --cached git -C ~/.abra/recipes/$ARGUMENTS ls-files --others --exclude-standard ``` **If there are uncommitted changes**, do NOT silently skip the fetch. Instead: - Show the user a concise summary of what's modified, staged, and untracked (with file paths and a few representative lines of diff). - Ask whether they want to: - **(a) commit and keep** — stage and commit the changes with a message they approve, then continue with fetch + rebase (`git rebase origin/main` after fetch), - **(b) stash temporarily** — stash with a descriptive label, then continue with fetch, and remind them to `git stash pop` afterwards, - **(c) discard** — only after explicit confirmation, run `git checkout -- .` and `git clean -fd`, then continue with fetch. - Do not invent a default — wait for the user's choice before proceeding. **If the working tree is clean**, run: ```bash abra recipe fetch $ARGUMENTS --force git -C ~/.abra/recipes/$ARGUMENTS fetch origin main ``` - `abra recipe fetch` pulls all tags and branches and checks out the latest tagged version. - The explicit `git fetch origin main` ensures `origin/main` is up to date even if the latest published tag is older than `main`. 3. **Check what already exists on upstream main** — before planning anything, compare the recipe's currently-checked-out version to `origin/main`: ```bash # Recent commits on upstream main git -C ~/.abra/recipes/$ARGUMENTS log origin/main --oneline -10 # Commits on origin/main that are NOT in the current checkout git -C ~/.abra/recipes/$ARGUMENTS log HEAD..origin/main --oneline ``` - If `origin/main` has commits beyond the current checkout, **inspect them carefully**. Someone may have already started the upgrade (image bumps, version label changes, env var additions). If yes, **re-plan from the tip of `origin/main`**, not from the deployed version — your goal becomes "what's left to add on top of what's already there," not "duplicate everything from scratch." - Also check upstream PRs at `https://git.coopcloud.tech/coop-cloud/$ARGUMENTS/pulls` for in-flight work that might overlap. 4. **Show current released versions and check for upgrades**: ``` abra recipe versions $ARGUMENTS -m abra recipe upgrade $ARGUMENTS -m -n ``` - If no upgrades are available, tell the user the recipe is already up to date and stop. 5. **Look up upstream release notes**: - Check if `recipe-info/$ARGUMENTS/upstream.md` exists in the workspace. - If it exists, read it to get the release notes URLs for each image/service. - If it does NOT exist, try to discover the upstream project and release notes URLs: - Read the recipe's `compose.yml` to identify all images. - For each image, search for its GitHub repository and releases page. - Create `recipe-info/$ARGUMENTS/upstream.md` with the discovered URLs (follow the format of existing upstream.md files in sibling recipe directories). - Also create the `recipe-info/$ARGUMENTS/tests/` directory if it doesn't exist. 6. **For each service with available upgrades**, fetch and summarise the release notes between the current version and the upgrade version(s). Pay special attention to and explicitly call out: - **Breaking changes** — API removals, renamed/removed config options, changed defaults, dropped support for older runtimes/dependencies - **Required migration steps** — database migrations, data format changes, manual upgrade procedures - **Config changes needed by the operator** — new required environment variables, changed variable names/formats, new secrets, changed ports or volume paths, deprecated settings that will stop working - **Dependency version requirements** — e.g. "now requires PostgreSQL 15+", "minimum Redis 6.2" - If any of the above are found, present them in a clearly marked "**Operator Action Required**" section per service. 7. **Read the recipe's README** at `~/.abra/recipes/$ARGUMENTS/README.md` (if it exists): - Check for upgrade-specific instructions, migration steps, or breaking change notes. 8. **Write upgrade info** for future reference: - Create the `planned-updates/` directory if it doesn't already exist. - Write all gathered information to `planned-updates/$ARGUMENTS-upgrade-info-.md` (using today's date). - The file should be structured markdown containing: - Current version(s) of the recipe - Available image tag upgrades - **Operator Action Required** items (breaking changes, config changes, migrations) - Changelog summaries with links to full release notes - Suggested next steps 9. **Create the upgrade plan**: - Create the `plans/` directory if it doesn't already exist. - Write an upgrade plan to `plans/$ARGUMENTS-upgrade-.md` (using today's date). - The plan focuses on **updating the recipe itself** (the compose.yml, config files, and recipe version label). It should include: - **Goal**: one-line summary (e.g. "Upgrade CryptPad recipe from 2025.9.0 to 2026.2.0 and nginx from 1.25 to 1.29") - **Image tag changes**: a table of service / current tag / new tag - **Upstream release-notes links**: the release-notes URL for each upgraded image/service (from `recipe-info/$ARGUMENTS/upstream.md`, between the current → new version), recorded verbatim so `/recipe-upgrade-apply` can put them in the **PR body** (`**Upstream release notes:** →: `), not just the report. - **Recipe version bump**: the semver reasoning (patch/minor/major) — i.e. which `abra recipe release` flag applies (`-z` patch / `-y` minor / `-x` major). The PR does **not** bump the `coop-cloud.*.version` label; `/recipe-upgrade-apply` records the recommended `abra recipe release -` in the PR body, and the label bump + tag + publish happen at the end via that real command (after the upstream PR merges — see `/recipe-upstream`). So just state the bump kind + reasoning here, not a version string. - **Recipe changes needed**: any modifications to compose.yml beyond the image tags — new env vars, changed config templates, new volumes, updated labels, added/removed services, etc. based on what the upstream release notes require - **Risks and caveats**: breaking changes from upstream, known issues from release notes, things that need manual verification - At the bottom, in a separate **Deployment** section (clearly marked as not part of the recipe update plan itself), briefly note: - The user can run `/recipe-upgrade-apply $ARGUMENTS` to apply the plan, deploy to the test instance, run tests, and commit/tag - Any post-deploy steps operators will need when applying this update to production (migration commands, scripts to run, etc.) 10. **Tell the user** the plan file path and suggest they review it, then run `/recipe-upgrade-apply $ARGUMENTS` to execute.