changed the update script to treat it like a monthly version release. including everything changed since the last version

This commit is contained in:
derekc committed 2026-11-17 22:39:15 -08:00
1 parent fbd626837f
commit 47b5ea5650
1 file changed
+67 -11
+67 -11
View File
@@ -1,11 +1,11 @@
---
description: Audit and update all software and dependencies, test each change, commit individually, write release notes, tag the release, push
description: 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
argument-hint: "[optional scope, e.g. 'patch and minor only' or 'skip docker']"
---
# Dependency & Software Update
Update everything this application depends on to current, supported versions. Work carefully and verify each change, and pause at the checkpoints marked **STOP** so I can review.
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
@@ -15,6 +15,8 @@ If this project's CLAUDE.md has an "Updates" section, follow it. It may list tes
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):
@@ -87,7 +89,39 @@ Rules:
- Don't disable, skip, or delete tests to make things pass.
- Don't push during this phase.
## Phase 4: Release notes
## 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`).
@@ -96,12 +130,32 @@ Write to `release-notes/YYYY.MM.md`, using the current year and month (e.g. `rel
- Match the style of earlier files in `release-notes/` if there are any. Otherwise use this structure:
```markdown
## YYYY-MM-DD: Dependency & software updates
## YYYY-MM-DD: vYYYY.MM release
### Summary
One or two sentences on what changed and anything notable.
One or two sentences on what's in this release (features, fixes, and updates) and anything notable.
### Updated
### 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 |
|---|---|---|---|---|
@@ -124,18 +178,20 @@ One or two sentences on what changed and anything notable.
- Restore command: the exact command for this backup
```
Commit it as `docs(release-notes): YYYY.MM dependency updates`.
Commit it as `docs(release-notes): vYYYY.MM`.
## Phase 5: Final verification and push (**STOP**)
## 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)
- 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 "YYYY.MM dependency updates"`. 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.
- **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:
@@ -147,7 +203,7 @@ Commit it as `docs(release-notes): YYYY.MM dependency updates`.
## Housekeeping
Run at the end of Phase 5, after the push. Rollback image tags pile up over time.
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.