Release

WebCalendar Release Skill

Drives the WebCalendar release process end-to-end. Most version-string updates are already automated by bump_version.sh; this skill orchestrates the surrounding steps that aren't (CHANGELOG, upgrade-SQL verification, branch merge, tag, GitHub release notes).

When to Activate

User asks to:

• "Cut a release" / "ship a release" / "tag vX.Y.Z"
• "Bump the version and release"
• "Create release vX.Y.Z"

Inputs

• New version (optional): vX.Y.Z. If omitted, auto-increment patch from current version.
• Release type (implied by version arg): patch / minor / major.

If the user gave no version, ask: "Auto-bump patch from <current> to <next-patch>, or do you want a different version?"

Step 1 — Pre-flight checks

Run these checks. Halt and report on any failure.

# Must be on master
git rev-parse --abbrev-ref HEAD                     # expect: master

# No modified tracked files. Untracked local files are chronic in this
# repo (a couple of dozen scratch files, roadmaps and local configs), so
# plain --porcelain is never empty and would halt every release. The bump
# itself happens in a fresh worktree (Step 3), which is clean by
# construction; what matters here is that master has no uncommitted edits.
git status --porcelain --untracked-files=no          # expect: empty

# Up to date with remote
git fetch origin
git log HEAD..origin/master --oneline               # expect: empty

# Current version
./bump_version.sh -p

If on a different branch, or a tracked file is modified: stop and ask the user how to proceed. Do not auto-stash or auto-checkout.

Release-manifest coverage check. Every git-tracked file must be classified: listed in release-files (ships in the ZIP) or matched by release-files-excluded (dev-only). Past releases shipped broken because new files were committed without updating release-files (#667, missing translations, export_wordpress.php).

# Enforced invariant — fails if any tracked file is unclassified
vendor/bin/phpunit -c tests/phpunit.xml --filter ReleaseFilesConsistencyTest

# Files added since the last release, with their classification
PREV_TAG=$(git describe --tags --abbrev=0)
git diff --diff-filter=A --name-only "$PREV_TAG"..HEAD

Show the user the list of files added since PREV_TAG and, for each, whether it ships (release-files) or is excluded (release-files-excluded). Ask the user to confirm the classification of any newly added file that landed in the excluded set — a runtime file wrongly excluded is exactly the drift that broke past releases. If the test fails, stop: classify the offending files (with the user) before proceeding.

Compute the new version:

• If user supplied vX.Y.Z, use that.
• Otherwise: bump_version.sh will auto-increment the patch when called with no arg.

State the planned version explicitly to the user before continuing.

Step 2 — Run local tests

Per maintainer policy, verify locally before triggering CI:

./tests/compile_test.sh                             # PHP syntax + composer.lock drift
vendor/bin/phpunit -c tests/phpunit.xml             # PHPUnit suite

Halt on any failure. Do not "fix and retry" — surface the failure to the user.

Step 3 — Bump the version

First: is this checkout also a live deployment? If the tree is served by a web server — /var/www/..., or includes/settings.php points at a database real users rely on — do not bump in it. upgrade_requires_db_changes() returns true for every version bump by design (includes/functions.php, "This ensures the wizard is triggered for every version bump"), so from the moment includes/config.php names a version ahead of the database, every request redirects to wizard/index.php. The site is down until the tree is switched back.

The mechanism is confirmed: upgrade_requires_db_changes() returns true for any newer version, from nested scope and on repeat calls, so the redirect branch is the one that runs. What that costs depends on whether a request arrives. When v1.9.24 was cut this way on 2026-09-26 the tree sat ahead of the database for about six minutes; whether a visitor hit it in that window was never established, so treat the exposure as "every request during the window", not as a measured outage.

Restoring the tree is not necessarily the whole recovery, because a request that does arrive can complete the wizard and upgrade the database — which is what appears to have happened on 2026-09-26. Then the roles reverse: the database is ahead of a restored tree, upgrade_requires_db_changes() finds nothing newer, returns false, and update_webcalendar_version_in_db() silently rewrites the stored version backwards to match the older code. A calendar can therefore end up with its version row flip-flopping as the tree is switched, with no record in the activity log.

The rewrite moves the version row; it does not undo applied SQL. That is the part to be careful about. After someone upgrades and the tree is then restored, the row understates the schema: it says vX.Y.(Z-1) while vX.Y.Z's statements have already run. Upgrading again from that row re-applies them. v1.9.24's one statement is explicitly idempotent, so this cost nothing on 2026-09-26 — but upgrade-sql.php contains 72 ALTER TABLE ... ADD statements across its history, and every one of those fails on a second run with a duplicate-column error.

So after any release attempt that was interrupted, reverted, or bounced between trees, check the version row against what has actually been applied rather than trusting the row:

php bin/webcal.php config get WEBCAL_PROGRAM_VERSION

and confirm it against the effect of that version's entry in wizard/shared/upgrade-sql.php. db check compares the row to the code, so it agrees with a row that is itself wrong.

Work in a git worktree instead, which leaves the served tree untouched:

git worktree add -b chore/release-vX.Y.Z /tmp/wc-release origin/master
ln -s "$PWD/vendor" /tmp/wc-release/vendor    # so the test suite can run
cd /tmp/wc-release

Three release-files guards markTestSkipped in a linked worktree (.git is a file there, so their git ls-files probe fails), so Step 1's manifest check must be run in the main checkout or trusted to CI.

Then bump:

./bump_version.sh                                   # auto-patch bump
# OR
./bump_version.sh vX.Y.Z                            # explicit version

This updates: includes/default_config.php, wizard/shared/upgrade_matrix.php, includes/config.php ($PROGRAM_VERSION + $PROGRAM_DATE), composer.json, composer.lock, .npmrc, wizard/shared/tables-*.sql, wizard/shared/tables-sqlite*.php, wizard/shared/upgrade-sql.php (adds empty placeholder entry), the four wizard files (index.php, headless.php, wizard.js, WizardState.php), and three documentation stamps: README.md's version badge, docs/WebCalendar-Database.md's **Version:** line, and CLAUDE.md's overview line where that file exists.

The documentation stamps are not cosmetic: tests/DocumentedVersionTest.php asserts all three against includes/config.php, so a release that bumps the code and not the docs fails the build. They must be staged with the rest (Step 8).

Confirm by running ./bump_version.sh -p — should show the new version.

Step 4 — Update CHANGELOG.md (auto)

bump_version.sh does not touch CHANGELOG.md. This skill must.

Open CHANGELOG.md. The file uses Keep a Changelog format with an ## [Unreleased] section near the top (after the intro paragraphs). Two edits:

A. Rename ## [Unreleased] → ## [vX.Y.Z] - YYYY-MM-DD

Use today's date in YYYY-MM-DD format (compute from date +%Y-%m-%d).

B. Insert a fresh ## [Unreleased] section directly above the new versioned heading

The fresh section must contain empty subsections so future contributors can drop entries in. Template:

## [Unreleased]

### Added

### Changed

### Fixed

### Removed

(Yes — empty subsections are intentional. They guide future PRs.)

After editing, show the user the diff for CHANGELOG.md so they can confirm before committing.

If the existing [Unreleased] section is empty (no entries under any subsection): stop and ask the user. A release with no changelog entries is suspicious — they may want to add entries or skip the release.

Step 5 — Verify wizard/shared/upgrade-sql.php

bump_version.sh appends a placeholder entry like:

  [
    'version' => 'vX.Y.Z',
    'default-sql' => ''
  ],

Open wizard/shared/upgrade-sql.php, locate the entry for the new version, and inspect its default-sql (and any postgresql-sql / sqlite3-sql / upgrade-function keys).

Two cases:

Case A — default-sql is non-empty (DB schema changes for this release): Show the user the SQL block(s) and ask: "Confirm these are the correct DB upgrade statements for vX.Y.Z?" Wait for confirmation before proceeding.

Case B — default-sql is empty: Ask the user explicitly: "No DB schema changes detected for vX.Y.Z. Confirm there are genuinely no DB changes for this release? (If there should be, edit wizard/shared/upgrade-sql.php now.)"

The empty-entry-as-marker convention matches prior no-DB-change releases (see v1.9.14 and v1.9.15 entries). Leaving the empty entry in place is the correct way to record "no DB changes for this version" — do not delete the entry.

Step 6 — Generate GitHub release notes

Write release notes to /tmp/release-notes-vX.Y.Z.md.

Source material, in order of priority:

1. The new ## [vX.Y.Z] section from CHANGELOG.md (just renamed in Step 4) — primary content.
2. Commit log since the previous tag, for cross-reference: git log <prev-tag>..HEAD --oneline. Use this to spot-check that the changelog is complete; if commits clearly missing from the changelog reference issues/PRs (fix(...): ... (#NNN)), include them.

Format (matches recent releases like v1.9.15):

# WebCalendar vX.Y.Z

<one-paragraph release summary — pull from CHANGELOG.md intro or write a 1-2 sentence summary>

## Added
- ...

## Changed
- ...

## Fixed
- ...

## Removed
- ...

## Verifying this release

WebCalendar releases ship a signed manifest. See `docs/release-signing.md` for verification instructions.

Drop empty subsections. Keep PR/issue references ((#NNN)) intact — they render as links on GitHub.

Show the user the generated notes and ask for edits before continuing.

Step 7 — Confirm before committing

Before any git commit, show the user:

• git status — files staged/changed
• git diff --stat — summary of changes
• The CHANGELOG.md diff (Step 4)
• The release notes preview (Step 6)
• The new version (./bump_version.sh -p)

Wait for explicit "go" / "yes" / equivalent confirmation. Do not assume.

Note that "cut the release" earlier in the conversation is authorisation for the release; it is not this confirmation, which is about the specific diff.