Maintains IdeaVim changelog (CHANGES.md) and build.gradle.kts changeNotes. Use when updating changelog, documenting releases, or reviewing commits/PRs for changelog entries.
# Get commits since last documented version
git log --oneline --since="YYYY-MM-DD" --first-parent master
# Get merged PRs
gh pr list --state merged --limit 100 --json number,title,author,mergedAt
# Check specific release commits
git log --oneline <previous-tag>..<new-tag>
Important: Don't just read commit messages - examine the actual changes:
Use git show <commit-hash> to see the full commit content
Look at modified test files to find specific examples of fixed commands
Check the actual code changes to understand what was really fixed or added
Tests often contain the best examples for changelog entries (e.g., exact commands that now work)
4. What to Include
Features: New functionality with [VIM-XXXX] ticket numbers if available
Bug Fixes: Fixed issues with [VIM-XXXX] ticket references
Breaking Changes: Any backwards-incompatible changes
Deprecations: Features marked for future removal
Merged PRs: Reference significant PRs like "Implement vim-surround (#123)"
Note: PRs have their own inclusion rules - see "Merged PRs Special Rules" section below
5. What to Exclude
Dependabot PRs (author: dependabot[bot])
Claude-generated PRs (check PR author/title)
Internal refactoring with no user impact
Documentation-only changes (unless significant)
Test-only changes
API module changes (while in experimental status) - Do not log changes to the api module as it's currently experimental
Note: This exclusion should be removed once the API status is no longer experimental
Vim Everywhere project (including Hints toggle) - Do not log changes related to the Vim Everywhere project as it's not yet ready
Internal code changes - Do not log coding changes that users cannot see or experience
Use web search to find the most relevant official sources
Include references: Add [VIM-XXXX] for YouTrack tickets, (#XXX) for PRs
Group logically: Features, Fixes, Changes, Merged PRs
No duplication: Each change appears in exactly ONE subsection - don't repeat items across categories
Use consistent tense: Past tense for completed work
Examples of Good Entries
### Features:
* Added support for `gn` text object - select next match with `gn`, change with `cgn`
* Implemented `:tabmove` command - use `:tabmove +1` or `:tabmove -1` to reorder tabs
* Support for `z=` to show spelling suggestions
* Added integration with [Next Edit Suggestion](https://blog.jetbrains.com/ai/2025/08/introducing-next-edit-suggestions-in-jetbrains-ai-assistant/) feature
* Support for [multiple cursors](https://www.jetbrains.com/help/idea/multicursor.html) in visual mode
### Fixes:
* [VIM-3456](https://youtrack.jetbrains.com/issue/VIM-3456) Fixed cursor position after undo in visual mode
* [VIM-3458](https://youtrack.jetbrains.com/issue/VIM-3458) Fixed `ci"` command now works correctly in empty strings
* [VIM-3260](https://youtrack.jetbrains.com/issue/VIM-3260) Fixed `G` command at file end with count
* [VIM-3180](https://youtrack.jetbrains.com/issue/VIM-3180) Fixed `vib` and `viB` selection in nested blocks
### Merged PRs:
* [805](https://github.com/JetBrains/ideavim/pull/805) by [chylex](https://github.com/chylex): VIM-3238 Fix recording a macro that replays another macro
IMPORTANT Format Notes
For Fixes:
Always put the ticket link FIRST, then the description:
* [VIM-XXXX](https://youtrack.jetbrains.com/issue/VIM-XXXX) Description of what was fixed
For Features:
Without ticket: Just the description
With ticket: Can use either format:
Description with pipe: * Feature description | [VIM-XXXX](https://youtrack.jetbrains.com/issue/VIM-XXXX)
Link first (like fixes): * [VIM-XXXX](https://youtrack.jetbrains.com/issue/VIM-XXXX) Feature description
Avoid Duplication:
Each change should appear in only ONE subsection
If a feature is listed in Features, don't repeat it in Fixes
If a bug fix is in Fixes, don't list it again elsewhere
Choose the most appropriate category for each change
Merged PRs Special Rules:
Different criteria than other sections: The exclusion rules for Features/Fixes don't apply here
Include PRs from external contributors even if they're internal changes or refactoring
List significant community contributions regardless of whether they're user-visible
Format: PR number, author, and brief description
Use PR title as-is: Take the description directly from the PR title, don't regenerate or rewrite it
Purpose: Acknowledge community contributions and provide PR tracking
The "user-visible only" rule does NOT apply to this section
Process
Read the current CHANGES.md (only the top portion - focus on [To Be Released] and recent versions)
Check previous changelog PRs from GitHub:
Review the last few changelog update PRs (use gh pr list --search "Update changelog" --state all --limit 5)
Read the PR comments: Use gh pr view <PR_NUMBER> --comments to check for specific instructions
Look for any comments or instructions about what NOT to log this time
Previous PRs may contain specific exclusions or special handling instructions
Pay attention to review feedback that might indicate what to avoid in future updates
Check git tags for any undocumented releases
Review commits and PRs since last entry
Group changes by release or under [To Be Released]
Update CHANGES.md maintaining existing format
Create a PR only if there are changes to document:
Title format: "Update changelog: <super short summary>"
Example: "Update changelog: Add gn text object, fix visual mode issues"
Body: Brief summary of what was added
build.gradle.ktschangeNotes is auto-derived from CHANGES.md at build time via the org.jetbrains.changelog plugin — do not touch it.
Important Notes
Don't create a PR if changelog is already up to date
Preserve existing format and structure
Maintain chronological order (newest first)
Keep the historical gap note between 2.9.0 and 2.28.0
