@@ -64,29 +64,36 @@ Gate execution checklist:
6464## 4. Release Preparation
6565
66661 . Ensure ` main ` is current and CI is green.
67- 2 . Finalize release notes (highlights, breaking changes, migration notes).
68- 3 . Confirm target tag does not already exist.
67+ 2 . ** Update CHANGELOG.md** with final release notes:
68+ - Change ` (Unreleased) ` to the release date ` (YYYY-MM-DD) `
69+ - Verify all breaking changes have migration guides
70+ - Ensure highlights, breaking changes, and migration notes are complete
71+ 3 . Commit and push CHANGELOG.md changes to ` main ` .
72+ 4 . Confirm target tag does not already exist.
6973
70- ## 5. Publish Release
74+ > ** Important** : The release workflow extracts release notes directly from CHANGELOG.md.
75+ > The ` ## vX.Y.Z ` section must be present and complete before triggering the release.
7176
72- 1 . Create and push annotated tag:
77+ ## 5. Publish Release
7378
74- ``` bash
75- git checkout main
76- git pull
77- git tag -a vX.Y.Z -m " Release vX.Y.Z"
78- git push origin vX.Y.Z
79- ```
79+ Use the GitHub Actions workflow dispatch to create the release:
8080
81- 2 . Create GitHub Release for that tag and publish release notes.
82- 3 . Set release title to exactly ` Version X.Y.Z ` .
83- 4 . Mark as ` Latest ` when appropriate.
81+ 1 . Go to Actions → "Prepare and Publish Release"
82+ 2 . Click "Run workflow" and fill in:
83+ - ** version** : ` X.Y.Z ` (without ` v ` prefix)
84+ - ** ref** : ` main ` (or specific commit SHA)
85+ - ** prerelease** : ` false ` (unless it's a prerelease)
86+ - ** confirm** : ` RELEASE ` (exactly, to confirm)
87+ 3 . The workflow will:
88+ - Run the full test matrix (PHP 8.2-8.5, prefer-lowest/prefer-stable, Ubuntu/Windows)
89+ - Extract release notes from CHANGELOG.md
90+ - Create the tag ` vX.Y.Z `
91+ - Create GitHub Release with title "Version X.Y.Z"
8492
8593## 6. Post-Release Checks
8694
87- 1 . Confirm ` Update Changelog ` workflow ran (` .github/workflows/update-changelog.yml ` ).
88- 2 . Confirm changelog update commit landed on ` main ` .
89- 3 . Confirm package update is visible on Packagist.
95+ 1 . Verify the GitHub Release was created with correct notes from CHANGELOG.
96+ 2 . Confirm package update is visible on Packagist.
90974 . Smoke-test install in clean project:
9198
9299``` bash
0 commit comments