Skip to content

Fix the release package, and write release notes for upgraders - #15

Merged
matasarei merged 2 commits into
masterfrom
fix/release-package
Aug 30, 2026
Merged

Fix the release package, and write release notes for upgraders#15
matasarei merged 2 commits into
masterfrom
fix/release-package

Conversation

@matasarei

Copy link
Copy Markdown
Collaborator

Found while verifying the published 3.0 artifact.

The package was missing its documentation

Two defects in the packaging step, both present in the 3.0 and 2.3 zips:

  • --exclude='*.md' stripped README.md and CHANGELOG.md. The published package carried
    no documentation at all. Only CLAUDE.md and AGENTS.md are dropped now.
  • rsync . release-package/local_cleanup/ copied the staging tree into itself, leaving an
    empty local_cleanup/release-package/local_cleanup/ inside the archive.

Verified by running the same rsync locally: README, CHANGELOG and LICENSE present; no .git,
.tasks, agent files or nested staging directory.

The release body was the wrong document

It was the entire changelog entry — every fix, every rename, five sections. That is the right
content for a changelog and the wrong content for somebody deciding whether to upgrade.

The workflow now prefers .github/release-notes/<tag>.md when it exists and falls back to the
changelog extraction otherwise. The changelog stays the full record; the release notes say what
to do.

.github/release-notes/3.0.md covers the four things a 2.x site has to check. Each was
verified against the code, and two of them I would have got wrong from the plan alone:

Managers gain read access 2.x gated on is_siteadmin(); 3.0 grants local/cleanup:view to manager. This is a widening, not a break — worth a deliberate revoke if unwanted
Only administrators can delete local/cleanup:deletefiles has no archetype; admins keep it by holding everything
Unlinked files pause for a week The new columns are not backfilled, so the first scan after upgrade sets timeconfirmed = timescanned = now, the grace check reads 0 < grace, and nothing is removed until a second scan ghostgracedays later. An operator will otherwise see the list stop shrinking and assume it is broken
$CFG->cleanup_* in config.php goes dead The upgrade calls unset_config(), which clears the database row but cannot edit config.php

Two things I expected to be breaking and checked instead of asserting: cli/cleanup.php is
new in 3.0, so no existing cron entry changes behaviour, and reinit_modules_cleanup.php
already required --force in 2.3.

The same four checks are in README.md, because .github/ is not shipped in the package.

Testing

php -l on 8.1 and 7.4, style sweep, YAML parse of the workflow, and the rsync simulation
above. No PHP changes, so CI is a regression check rather than a verification of this diff.

Notes

  • The published 3.0 assets are still the broken ones. Re-cutting the tag after this merges is
    the follow-up.

matasarei and others added 2 commits August 30, 2026 20:07
…tory

Two defects in the packaging step, both present in the 3.0 and 2.3 artifacts:

--exclude='*.md' stripped README.md and CHANGELOG.md, so the published zip
carried no documentation at all - the plugins directory expects both, and
README is now the primary operator reference. Only CLAUDE.md and AGENTS.md
are dropped now.

release-package/ sits inside the directory rsync copies, so the staging tree
was copied into itself, leaving an empty local_cleanup/release-package/
local_cleanup/ inside the archive.

Verified by running the same rsync locally: README, CHANGELOG and LICENSE
present, no .git, .tasks, agent files or nested staging directory.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SrD1CtCf7ERCCtH2k7LzK3
The release body was the whole changelog entry, which is the wrong document
for somebody deciding whether to upgrade. The workflow now uses
.github/release-notes/<tag>.md when it exists and falls back to the changelog
extraction otherwise, so the changelog stays the full record and the release
notes say what to do.

The 3.0 notes cover the four things a 2.x site has to check, all verified
against the code rather than the plan: managers gain read access where 2.x was
site-admin-only, nobody but an administrator can delete, unlinked files pause
for a week because the new columns are not backfilled and the first scan after
upgrade is the first sighting, and any $CFG->cleanup_* lines in config.php are
now dead because unset_config cannot reach them.

The same four are in README.md, since .github/ is not shipped in the package.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SrD1CtCf7ERCCtH2k7LzK3
@matasarei
matasarei merged commit 4f22b8a into master Aug 30, 2026
4 checks passed
@matasarei
matasarei deleted the fix/release-package branch August 30, 2026 17:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant