[How to] Use Cursor to automate your project's changelogs
This is for those interested in using Cursor to automate your project's changelogs, tags, and releases. I use this workflow for OddsRabbit, with the changelogs updated live here if you want to see an example.
First create two files in your project folder changelog.md and changelog-rules.md.
Inside changelog.md, copy and paste the following:
# Changelog
## [Unreleased]Inside changelog-rules.md copy and paste the following:
#Changelog Rules
All notable changes to this project will be documented in changelog.md.
#Version Numbering
This project uses a three-number versioning system (X.Y.Z):
X (Major): Breaking changes, major feature overhauls
Y (Minor): New features, significant improvements
Z (Patch): Bug fixes, minor improvements
Example: Version 1.2.3
1: Major version
2: Minor version
3: Patch version
When to increment:
Major (X): When making incompatible changes that might break existing functionality
Minor (Y): When adding functionality in a backward-compatible manner
Patch (Z): When making backward-compatible bug fixes
#Making Changelog Entries
#For New Changes in Development:
Add changes under the [Unreleased] section
Categorize them under appropriate headers:
Added for new features
Changed for changes in existing functionality
Deprecated for soon-to-be removed features
Removed for removed features
Fixed for bug fixes
Security for vulnerability fixes
Technical for technical changes/dependencies
Keep entries concise but descriptive
#When Releasing a Version:
Convert the [Unreleased] section to a version number with today's date (e.g., [1.0.0] - 2024-01-20)
Create a new empty [Unreleased] section at the top
#General Rules:
Newest changes always go at the top of the file
Each version should be in descending order (newest to oldest)
Group related changes under the same category
Use bullet points for each entry
#Development Workflow:
For Every Code Change:
ALWAYS add an entry to the [Unreleased] section in this changelog
Write clear, descriptive change notes
Categorize changes appropriately using the headers above
Commit changes with meaningful commit messages
For Version Releases:
Move [Unreleased] changes to a new version section with today's date
Update version number in ProjectSettings.asset (bundleVersion)
Create a git tag for the version
Create a new empty [Unreleased] section at the top
#Release Process:
When asked to make a release, follow these steps:
Review Changes:
Review all changes under [Unreleased]
Ensure all changes are properly categorized
Verify all changes are documented
Choose Version Number:
For new features: increment minor version (0.1.0 → 0.2.0)
For bug fixes: increment patch version (0.1.0 → 0.1.1)
For breaking changes: increment major version (0.1.0 → 1.0.0)
Update Files:
Move [Unreleased] changes to new version section with today's date
Create new empty [Unreleased] section
Commit and Tag:
Commit all changes with message "release: Version X.Y.Z"
Create a git tag for the version (e.g., v0.2.0)You can edit changelog-rules.md to fit your personal or company preferences.
Now you want to edit your Rules for AI, which can be accessed under File -> Preferences -> Cursor Settings. Copy and paste the following into your Rules for AI:
ALWAYS update the Changelog.md under [Unreleased] when making any change. Follow the rules in changelog-rules.md for making changes to the changelog.
When Asked to Commit Staged Changes always check changelog to see if the changes in staged files are represented in the changelog before commiting). If the changes in the staged files are not represented in the changelog, follow the rules in changelog-rules.md to add the changes to changelog.md under [Unrelease]. To check for changes, use git --no-pager diff --cached.
When releasing: Review [Unreleased] changes to determine version bump (features→minor, fixes→patch, breaking→major), move changes to new version section with date, commit as "release: Version X.Y.Z", and create git tag. When releasing, also create a release via Github CLI. The release notes should not contain newlines and instead use proper formatting.That's it. Now whenever you're ready to make a commit, just staged the files you want to push and open up Composer. Tell it to commit staged changes (or commit staged changes, tag, and release) and go through the flow. It will automatically update your changelog.md with a summary of your latest changes under ## [Unreleased].
When you're ready to release, tell Composer to tag and release, and it will automatically create a new release with all of your unreleased changes.
Hope this helps!
Comments
No comments yet. Why don't you leave the first?