diff --git a/.claude/commands/update-changelog.md b/.claude/commands/update-changelog.md index ab0c36a9d8..78c1cbd106 100644 --- a/.claude/commands/update-changelog.md +++ b/.claude/commands/update-changelog.md @@ -95,45 +95,72 @@ This will: - Add headers for the new version - Update version diff links at the bottom of the file +### Version Links + +After adding an entry to the `## [Unreleased]` section, ensure the version diff links at the bottom of the file are correct. + +The format at the bottom should be: + +```markdown +[Unreleased]: https://github.com/shakacode/react_on_rails/compare/v16.0.0...master +[v16.0.0]: https://github.com/shakacode/react_on_rails/compare/v15.0.0...v16.0.0 +``` + +When a new version is released: + +1. Change `[Unreleased]` heading to `## [vX.Y.Z] - Month Day, Year` +2. Add a new `## [Unreleased]` section at the top +3. Update the `[Unreleased]` link to compare from the new version +4. Add a new version link for the released version + ## Process ### For Regular Changelog Updates -1. **Determine the correct version tag to compare against**: +1. **ALWAYS fetch latest changes first**: + + - **CRITICAL**: Run `git fetch origin master` to ensure you have the latest commits + - The workspace may be behind origin/master, causing you to miss recently merged PRs + - After fetching, use `origin/master` for all comparisons, NOT local `master` branch + +2. **Determine the correct version tag to compare against**: - First, check the tag dates: `git log --tags --simplify-by-decoration --pretty="format:%ai %d" | head -10` - Find the latest version tag and its date - - Compare main branch date to the tag date - - If the tag is NEWER than main, it means main needs to be updated to include the tag's commits + - Compare origin/master branch date to the tag date + - If the tag is NEWER than origin/master, it means the branch needs to be updated to include the tag's commits - **CRITICAL**: Always use `git log TAG..BRANCH` to find commits that are in the tag but not in the branch, as the tag may be ahead -2. **Check commits and version boundaries**: +3. **Check commits and version boundaries**: - - Run `git log --oneline LAST_TAG..master` to see commits since the last release - - Also check `git log --oneline master..LAST_TAG` to see if the tag is ahead of master + - **IMPORTANT**: Use `origin/master` in all commands below, not local `master` + - Run `git log --oneline LAST_TAG..origin/master` to see commits since the last release + - Also check `git log --oneline origin/master..LAST_TAG` to see if the tag is ahead of origin/master - If the tag is ahead, entries in "Unreleased" section may actually belong to that tagged version - - Identify which commits contain user-visible changes - - Extract PR numbers and author information from commit messages - - **Never ask the user for PR details** - get them from the git history + - **Extract ALL PR numbers** from commit messages using grep: `git log --oneline LAST_TAG..origin/master | grep -oE "#[0-9]+" | sort -u` + - For each PR number found, check if it's already in CHANGELOG.md using: `grep "PR XXX" CHANGELOG.md` (note: no hash in search since React on Rails uses no hash) + - Identify which commits contain user-visible changes (look for keywords like "Fix", "Add", "Feature", "Bug", etc.) + - Extract author information from commit messages + - **Never ask the user for PR details** - get them from the git history or use WebFetch on the PR URL -3. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits. +4. **Validate** that changes are user-visible (per the criteria above). If not user-visible, skip those commits. -4. **Read the current CHANGELOG.md** to understand the existing structure and formatting. +5. **Read the current CHANGELOG.md** to understand the existing structure and formatting. -5. **Determine where entries should go**: +6. **Determine where entries should go**: - - If the latest version tag is NEWER than master branch, move entries from "Unreleased" to that version section - - If master is ahead of the latest tag, add new entries to "Unreleased" + - If the latest version tag is NEWER than origin/master branch, move entries from "Unreleased" to that version section + - If origin/master is ahead of the latest tag, add new entries to "Unreleased" - Always verify the version date in CHANGELOG.md matches the actual tag date -6. **Add or move entries** to the appropriate section under appropriate category headings. +7. **Add or move entries** to the appropriate section under appropriate category headings. - **CRITICAL**: When moving entries from "Unreleased" to a version section, merge them with existing entries under the same category heading - **NEVER create duplicate section headings** (e.g., don't create two "### Fixed" sections) - If the version section already has a category heading (e.g., "### Fixed"), add the moved entries to that existing section - Maintain the category order as defined above -7. **Verify formatting**: +8. **Verify formatting**: - Bold description with period - Proper PR link (NO hash symbol) @@ -141,14 +168,13 @@ This will: - Consistent with existing entries - File ends with a newline character -8. **Run linting** after making changes: +9. **Run linting** after making changes: ```bash - bundle exec rubocop - yarn run lint + yarn lint ``` -9. **Show the user** the added or moved entries and explain what was done. +10. **Show the user** the added or moved entries and explain what was done. ### For Beta to Non-Beta Version Release