Files
AI/slash-commands/update-deps.md
T

15 KiB

description, argument-hint
description argument-hint
Monthly version release. Audit and update all software and dependencies, test each change, commit individually, summarize changes since the last release, update the README, write release notes, tag the release, push [optional scope, e.g. 'patch and minor only' or 'skip docker']

Dependency & Software Update

Each run of this command is a monthly version release. Update everything this application depends on to current, supported versions, capture everything that changed in the project since the last release, and ship it as a tagged version. Work carefully and verify each change, and pause at the checkpoints marked STOP so I can review.

Extra scope or instructions for this run (may be empty): $ARGUMENTS

If this project's CLAUDE.md has an "Updates" section, follow it. It may list test commands, smoke-test URLs, pinned versions, or packages to leave alone, and it takes priority over the defaults below.

Phase 0: Preflight

  1. Run git status. If the working tree is not clean, STOP and tell me. Do not stash or commit my in-progress work.
  2. Note the current branch and confirm it tracks a remote. Record the starting commit (git rev-parse HEAD) as <START_SHA>. It's the rollback reference for the code.
    • Run git fetch --tags, then find the previous release: git describe --tags --abbrev=0 --match "v[0-9]*". Record it as <PREV_TAG>.
    • If there's no previous release tag (first run), use the date of the most recent release-notes/ entry to find a starting commit if one exists. Otherwise tell me and ask whether to cover the full history or start from a commit I pick.
  3. Find out how this project builds, tests, lints, and runs. Check CLAUDE.md, README, package scripts, Makefile, Dockerfile, and docker-compose files.
  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 <DATE> (YYYY-MM-DD):
    • 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 <image>:<current-tag> <image>:<current-tag>-pre-update-<PROJECT>-<DATE> (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.
      • <PROJECT> 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

  • Location: use the backup path from CLAUDE.md's "Updates" section if one is set. Otherwise use ~/backups/<project-name>/. It must be outside the repo. Create it with chmod 700, make each backup file chmod 600, and never commit a backup.
  • Filename: <db-name>-pre-update-<DATE>.<ext>
  • Method: take a consistent backup without stopping the app when the database supports it. Get credentials from the running container's environment or the compose/env files. Never print passwords in your output.
    • PostgreSQL: docker compose exec -T <svc> pg_dump -U <user> -Fc <db> > <file>.dump
    • MySQL/MariaDB: docker compose exec -T <svc> mysqldump --single-transaction -u <user> -p"$PASS" <db> > <file>.sql, then gzip it
    • SQLite: sqlite3 <db-file> ".backup '<file>.sqlite'". Never use a plain cp on a live SQLite file.
    • MongoDB: mongodump --archive --gzip
    • Redis or caches that only hold rebuildable data: skip them and say so.
    • Anything else (an unknown volume, a database that can't be dumped live): STOP and ask me before stopping containers to tar the volume, because that means downtime.
  • Verify the backup before moving on. The file must not be empty, and it must pass a quick check that it can be read: pg_restore --list for Postgres, PRAGMA integrity_check for SQLite, gunzip -t for gzipped dumps, or checking that a .sql file ends with the dump-complete marker. Report the file's size and path.
  • Write down the restore command for this specific backup. It goes in the release notes Rollback section. Don't run a restore unless I ask.
  • Pruning: keep the 5 most recent pre-update backups for each database. List any older ones and ask before deleting them.

Phase 1: Inventory

Check every layer that applies, not just the main package manifest:

  • Language runtime: Node, Python, Go, PHP, etc. Look at .nvmrc, .python-version, engines, pyproject.toml, go.mod, and Docker base images.
  • App dependencies: npm/pnpm/yarn, pip/poetry/uv, composer, go modules, etc. Use the ecosystem's own tools (npm outdated, pip list --outdated, go list -m -u all, ...).
  • Container images: FROM lines in Dockerfiles and image: tags in compose files, including databases, Redis, reverse proxies, and other sidecars. Check for newer tags and whether the current tag is still supported.
  • OS packages installed in Dockerfiles.
  • Tooling: build tools, linters, test frameworks, TypeScript, bundlers.
  • CI config, if present (GitHub Actions versions, etc.).
  • Security: run npm audit, pip-audit, or the equivalent. Note any CVEs, especially ones affecting current versions.

For every major version bump, and for runtime or database image bumps, read the changelog or migration guide and list the breaking changes that actually affect this codebase (search the code for the affected APIs).

Phase 2: Plan (STOP)

Present a table:

| Component | Current | Latest | Type (patch/minor/major) | Security fix? | Breaking changes affecting us | Plan |

Then give a proposed update order:

  1. Security fixes first
  2. Patch and minor updates (related packages grouped, e.g. a framework and its @types or plugins)
  3. Major updates, one per commit
  4. Runtime and base image updates last

Call out anything you recommend skipping or deferring and why (e.g. a major version that requires a rewrite, or a version that is too new or unstable). Never move a database image across a major version without my explicit approval, because that can require a data migration.

Wait for my approval before changing anything.

Phase 3: Apply, one unit at a time

For each update unit in the approved order:

  1. Make the change and regenerate lockfiles with the project's package manager. Do not hand-edit lockfiles.
  2. Apply any code changes the update requires.
  3. Verify: build, tests, lint, and, where applicable, a container build plus a quick smoke test (start the app, hit the health/home endpoint, then shut it down).
  4. If verification passes and matches the baseline, commit just this unit:
    • Format: chore(deps): bump <name> <old> → <new>. Use fix(deps): for security fixes and feat!/chore(deps)!: with a body for majors that needed code changes.
    • In the commit body, briefly note any code changes and why.
  5. If it fails: make a reasonable attempt to fix it. If the fix becomes large or risky, revert this unit (git checkout -- . / restore the lockfile), record it as deferred with the error, and continue with the next unit.

Rules:

  • Don't commit secrets, .env files, or build output.
  • Don't skip git hooks (--no-verify) and don't force-push.
  • Don't disable, skip, or delete tests to make things pass.
  • Don't push during this phase.

Phase 4: Changes since the last release

Collect everything that landed in the project since <PREV_TAG>, not just this run's dependency bumps.

  1. List the commits: git log <PREV_TAG>..<START_SHA> --no-merges --format="%h %ad %an %s" --date=short. This run's dependency commits (after <START_SHA>) are covered separately in the release notes "Updated" table.
  2. Get the scope of changes: git diff --stat <PREV_TAG>..<START_SHA>. Where a commit message is vague ("fix", "wip", "updates"), read that commit's diff (git show <sha>) to work out what actually changed.
  3. Group the changes for the release notes:
    • Added: new features, pages, endpoints, commands, settings
    • Changed: behavior or UI changes, refactors that affect users or deployment
    • Fixed: bug fixes
    • Removed: removed features, endpoints, settings, or files
    • Internal: tooling, CI, docs, and cleanup with no user-facing effect (keep this short)
  4. Write each item in plain language from the user's or admin's point of view, with the short commit hash(es) in parentheses. Combine related commits into one item.
  5. Flag anything that affects deployment: new or renamed env vars (check .env.example), database migrations or schema changes, compose/port/volume changes, new required services. These go in the release notes and the Phase 7 deploy checklist.
  6. If there are no commits since <PREV_TAG>, say so. The release still goes ahead for the dependency updates.

Phase 5: README update

Bring the project's README in line with the current state of the project, using the Phase 4 changes and this run's updates.

  1. Read the README in full and check it against the code as it is now:
    • Versions: runtime, database, and base image versions mentioned in the text
    • Setup and install steps, commands, and scripts
    • Configuration: env vars and settings (compare with .env.example and config files)
    • Features and usage: add new features, update changed ones, remove anything that no longer exists
    • Ports, URLs, endpoints, and folder structure
    • Version/release info, if the README shows a current version or links to release notes
  2. Edit only what is out of date, missing, or wrong. Keep the existing structure, tone, and formatting. Don't rewrite sections that are still accurate, and don't add new sections unless a new feature needs one.
  3. If there's no README, don't create one. Note it in the summary instead.
  4. If nothing needs changing, say so and skip the commit.
  5. Otherwise commit it as docs(readme): update for vYYYY.MM, with a short body listing what was added, updated, or removed.

Phase 6: Release notes

Write to release-notes/YYYY.MM.md, using the current year and month (e.g. release-notes/2026.10.md).

  • If the file already exists, append a new dated section. Never overwrite or rewrite earlier entries.
  • If it doesn't exist, create it with a # YYYY.MM Release Notes heading.
  • Match the style of earlier files in release-notes/ if there are any. Otherwise use this structure:
## YYYY-MM-DD: vYYYY.MM release

### Summary
One or two sentences on what's in this release (features, fixes, and updates) and anything notable.

### Changes since <PREV_TAG>
#### Added
- <item> (<hash>)
#### Changed
- <item> (<hash>)
#### Fixed
- <item> (<hash>)
#### Removed
- <item> (<hash>)
#### Internal
- <item> (<hash>)

(Leave out empty subsections. If there were no commits since the last release, write "No changes since <PREV_TAG> other than the dependency updates below.")

### Deployment notes
- New/changed env vars, migrations, compose or volume changes (or "None")

### Documentation
- README changes made in this release (or "None")

### Dependency updates
| Component | From | To | Type | Notes |
|---|---|---|---|---|

### Security
- CVE / advisory → fixed by <package> <version> (or "None")

### Code changes
- Changes made to support updates (or "None")

### Deferred / skipped
- <component> <version>: reason, and what's needed to do it later

### Verification
- Build / tests / lint / container build / smoke test results

### Rollback
- Starting commit: `<START_SHA>`
- Image tags: `<image>:<current-tag>-pre-update-<PROJECT>-<DATE>` (list each)
- Database backup: path and size, or "not applicable"
- Restore command: the exact command for this backup

Commit it as docs(release-notes): vYYYY.MM.

Phase 7: Final verification and push (STOP)

  1. Do a clean verification from scratch: fresh dependency install (npm ci, a clean venv, etc.), full build, full test suite, and docker build --no-cache if there's a Dockerfile.
  2. Show me:
    • git log --oneline of the commits made in this run
    • The "Changes since <PREV_TAG>" summary from the release notes
    • The README diff (git show of the README commit), or "no README changes"
    • Before and after test results compared with the baseline
    • Deferred items
    • Anything I need to do manually on deploy (env var changes, DB migrations, volume or permission changes, image re-pulls), including deployment-affecting changes found in Phase 4
  3. Ask me to confirm, then:
    • Create a release tag on the final commit, named vYYYY.MM with the current year and month (e.g. v2026.11), matching the release notes file: git tag -a vYYYY.MM -m "vYYYY.MM release". If that tag already exists (a second run in the same month), add a suffix like -2. Never move or overwrite an existing release tag.
    • Push the commits and the release tag together: git push && git push origin vYYYY.MM.
    • If any final check fails, don't tag or push. Explain what failed instead.
  4. Print the rollback commands specific to this project. Fill in the real tag and image names:
    • Undo one bad update: git revert <commit>, then rebuild and redeploy
    • Undo the whole run: git revert --no-edit <START_SHA>..HEAD, then rebuild and redeploy
    • Run the old images immediately: change the image tags in compose to <current-tag>-pre-update-<PROJECT>-<DATE>, 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

Run at the end of Phase 7, after the push. Rollback image tags pile up over time.

  • Scope: only touch tags matching *-pre-update-<PROJECT>-* 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-<PROJECT>-".
  • 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 <image>:<tag> 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 (<image>:pre-update-<DATE> 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.