diff --git a/slash-commands/update-deps.md b/slash-commands/update-deps.md index cecb420..f02f587 100644 --- a/slash-commands/update-deps.md +++ b/slash-commands/update-deps.md @@ -19,7 +19,10 @@ If this project's CLAUDE.md has an "Updates" section, follow it. It may list tes 4. **Run a baseline** of build, tests, lint, and (if possible) a container build, *before changing anything*. Record what passes and what already fails, so that later failures can be traced to a specific update and pre-existing problems aren't blamed on it. 5. **Create a rollback point** before changing anything. Use today's date as `` (YYYY-MM-DD): - **Code:** `git tag pre-update-`. Add a suffix like `-2` if that tag already exists. - - **Images:** for each image this project builds or runs (from the Dockerfile and compose files), tag the version currently in use: `docker tag : :pre-update-`. List the tags you created. + - **Images:** for each image this project builds or runs (from the Dockerfile and compose files), tag the version currently in use with a **project-scoped** tag: `docker tag : :-pre-update--` (e.g. `mysql:8.0-pre-update-myapp-2026-11-17`). Shared images like `mysql` or `redis` are often used by several projects on the same server, so the project name keeps one project's rollback tags from overwriting another's. + - `` is the compose project name (`docker compose config --format json` → `name`), or the repo folder name if there is no compose file. Lowercase it and replace anything other than `a-z 0-9 . _ -` with `-`. + - If the tag already exists (a second run on the same day), add a suffix like `-2`. + - List the tags you created. - **Data:** if the project has a database or stateful volume, back it up yourself (see "Database backup" below) before any changes. If the backup fails or can't be verified, **STOP**. Do not continue the update without a good backup. ### Database backup @@ -117,7 +120,7 @@ One or two sentences on what changed and anything notable. ### Rollback - Git tag: `pre-update-` -- Image tags: `:pre-update-` (list each) +- Image tags: `:-pre-update--` (list each) - Database backup: path and size, or "not applicable" - Restore command: the exact command for this backup ``` @@ -136,9 +139,16 @@ Commit it as `docs(release-notes): YYYY.MM dependency updates`. 4. Print the rollback commands specific to this project. Fill in the real tag and image names: - Undo one bad update: `git revert `, then rebuild and redeploy - Undo the whole run: `git revert --no-edit pre-update-..HEAD`, then rebuild and redeploy - - Run the old images immediately: change the image tags in compose to `pre-update-`, then `docker compose up -d` + - Run the old images immediately: change the image tags in compose to `-pre-update--`, then `docker compose up -d` - Restore the database from the backup, only if a schema or data migration happened +5. Run **Housekeeping** (below) for this project's image tags. ## Housekeeping -Rollback tags pile up over time. When there are more than 3 `pre-update-*` image tags for an image, list the older ones and ask whether to remove them with `docker rmi :pre-update-`. Keep git tags. They cost nothing. +Run at the end of Phase 5, after the push. Rollback image tags pile up over time. + +- **Scope:** only touch tags matching `*-pre-update--*` for this project's images. Never remove another project's `pre-update` tags, even if they're on the same image. List them with `docker images --format '{{.Repository}}:{{.Tag}}' | grep -- "-pre-update--"`. +- **Keep:** this run's tags plus the 2 most recent earlier runs (3 runs total) for each image. +- **Prune:** list the older tags and **ask me** before running `docker rmi :` on them. Removing a tag only deletes the image if no other tag or container still uses it, so a shared image used by another project stays. +- Old-format tags (`:pre-update-` with no project name) came from earlier runs and may belong to any project. List them separately, but don't include them in the prune unless I say so. +- Keep git tags. They cost nothing.