A changelog is a file that lists what changed in each version of your project. You create a CHANGELOG.md file in your repository, organize entries by version number and date, and group changes under categories like Added, Changed, Fixed, and Removed. GitHub Releases let you publish the same information with downloadable assets attached.
Why Every Project Needs a Changelog
A changelog answers the most common question anyone asks about a project: "What's new?" Whether it's your co-founder, a beta tester, or a contractor joining the project, a changelog gives them a clear history of what has been added, changed, fixed, or removed in each version. Think of it like release notes on an iPhone update — except for your app. The standard format, recommended by keepachangelog.com, uses semantic version numbers (like 1.0.0, 1.1.0, 1.2.0) and dates, with changes grouped into categories: Added (new features), Changed (modifications to existing features), Fixed (bug repairs), and Removed (things taken away). If you're building with AI tools like Lovable or V0, your project evolves quickly as you prompt new features. A changelog helps you remember what each round of changes actually did, which becomes invaluable when something breaks and you need to trace it back to a specific version.
Prerequisites
- A GitHub account with a repository
- Basic Markdown knowledge (headings, lists)
- At least one version or update of your project to document
Step-by-step guide
Create a CHANGELOG.md file in your repository
Create a CHANGELOG.md file in your repository
Navigate to your repository on github.com. Click the "Add file" dropdown button above the file list and select "Create new file." In the filename field, type "CHANGELOG.md" — use all uppercase letters for the name, which is the convention that makes the file easy to spot in a file list. The .md extension means it uses Markdown formatting, just like your README. GitHub will render it as a nicely formatted document when anyone views it.
Expected result: You see a blank editor with "CHANGELOG.md" as the filename.
Add the file header and format your first version entry
Add the file header and format your first version entry
Start with a heading: type "# Changelog" on the first line. On the next line, add a brief description like: "All notable changes to this project will be documented in this file." Leave a blank line, then add your first version entry. Type "## [1.0.0] - 2026-03-28" (replace the date with today's date). The square brackets around the version number are a convention that you can later turn into links. Below the version heading, add category subheadings: "### Added" for new features, "### Changed" for modifications, "### Fixed" for bug fixes. Under each subheading, list changes as bullet points starting with a dash.
Expected result: Your editor shows a version heading with date, category subheadings, and bullet-point changes.
Write clear and specific change descriptions
Write clear and specific change descriptions
Each bullet point should describe one specific change in plain language. Instead of writing "Updated the app" (too vague), write "Added user authentication with email and password via Supabase." Instead of "Fixed a bug," write "Fixed dashboard crash when filtering by date range with no data." Start each entry with a past-tense verb: Added, Changed, Fixed, Removed, Improved, Updated. If you're using AI tools like Cursor or Lovable and they generate commit messages, you can reference those messages as a starting point — but rewrite them in human-friendly language for the changelog.
Expected result: Each bullet point starts with a verb and describes a specific, understandable change.
Add entries for previous versions if applicable
Add entries for previous versions if applicable
If your project has had multiple rounds of updates, add previous version sections below the latest one. Each version gets its own ## heading with a version number and date. List them in reverse chronological order — the newest version at the top, oldest at the bottom. For example, below your [1.0.0] section, add "## [0.2.0] - 2026-03-15" with its own changes. If you're starting fresh and don't have prior versions, that's fine — just start with [1.0.0] and add new entries as you make updates.
Expected result: Your changelog has at least one version entry, with the most recent version at the top.
Commit the changelog file to your repository
Commit the changelog file to your repository
Click the green "Commit changes" button below the editor. In the commit message field, type "Add changelog to track project updates." Make sure "Commit directly to the main branch" is selected, then click "Commit changes" in the dialog. Your CHANGELOG.md file now appears in the repository file list and is rendered as a formatted Markdown document when clicked.
Expected result: CHANGELOG.md is visible in your repository's file list alongside README.md.
Create a GitHub Release to match your changelog entry
Create a GitHub Release to match your changelog entry
GitHub Releases are a way to formally publish a version with a description and optional downloadable files. On your repository page, look at the right sidebar and click "Releases" (or click the "Releases" link from the Code tab). Click the "Create a new release" button. In the "Tag version" field, type "v1.0.0" (matching your changelog version). Give the release a title like "v1.0.0 — Initial Release." In the description box, copy the changelog entries for this version. Click the green "Publish release" button. The release now appears on your repository's Releases page with a permanent link.
Expected result: A published release appears on the Releases page with your version tag, title, and description.
Complete working example
1# Changelog23All notable changes to this project will be documented in this file.45The format is based on [Keep a Changelog](https://keepachangelog.com/),6and this project adheres to [Semantic Versioning](https://semver.org/).78## [1.1.0] - 2026-03-28910### Added1112- User profile page with avatar upload13- Email notification preferences in settings14- Export data to CSV from the dashboard1516### Changed1718- Improved loading speed on the dashboard by 40%19- Updated Supabase client library to latest version2021### Fixed2223- Fixed login redirect loop on Safari browsers24- Fixed date picker not showing correct timezone2526## [1.0.0] - 2026-03-152728### Added2930- Initial release with user authentication31- Dashboard with real-time data visualization32- Settings page for account management33- Responsive design for mobile devicesCommon mistakes when writing a Changelog on GitHub
Why it's a problem: Writing vague entries like "Updated stuff" or "Bug fixes"
How to avoid: Be specific. Write "Fixed checkout page crashing when cart is empty" instead of "Bug fixes." Users need to know exactly what changed.
Why it's a problem: Not using a consistent date format
How to avoid: Always use YYYY-MM-DD (like 2026-03-28). Avoid formats like March 28th or 28/03/2026 which are ambiguous across countries.
Why it's a problem: Putting the oldest version at the top
How to avoid: Changelogs should be in reverse chronological order — newest version first. This way visitors immediately see the latest changes.
Why it's a problem: Forgetting to update the changelog when making changes
How to avoid: Make it a habit to update CHANGELOG.md in the same commit as the change, or add it to your workflow checklist. A stale changelog is worse than none.
Best practices
- Follow the Keep a Changelog format (keepachangelog.com) for consistency
- Use semantic versioning: MAJOR.MINOR.PATCH (1.0.0, 1.1.0, 1.1.1)
- Group changes under Added, Changed, Fixed, Removed, Deprecated, and Security categories
- Write entries in plain language that non-technical stakeholders can understand
- Update the changelog with every meaningful change, not just major releases
- Create a matching GitHub Release for each version to give it a permanent, shareable link
- Start each bullet point with a past-tense verb for clarity and consistency
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I've been building an app with Lovable and I have these recent changes: added user profiles, fixed a login bug, updated the dashboard design. Write a properly formatted CHANGELOG.md entry using the Keep a Changelog format with version 1.2.0 and today's date.
Frequently asked questions
What is semantic versioning?
Semantic versioning uses three numbers: MAJOR.MINOR.PATCH. Increment MAJOR for breaking changes, MINOR for new features that don't break anything, and PATCH for bug fixes. For example, going from 1.0.0 to 1.1.0 means a new feature was added.
Do I need both a CHANGELOG.md and GitHub Releases?
Not necessarily, but they complement each other. CHANGELOG.md is a single file with the complete history. GitHub Releases are individual pages with permanent links that you can share. Many projects maintain both.
How often should I update the changelog?
Update it with every meaningful release or batch of changes. If you're iterating quickly with Lovable or V0, you might update weekly. For stable projects, update with each version release.
Can I automatically generate a changelog from commits?
Yes, there are tools that generate changelogs from commit messages, but they require consistent commit message formatting. For non-technical founders, manually writing clear entries is usually better than auto-generated technical commit messages.
Where should CHANGELOG.md be located in my repository?
Place it in the root directory of your repository, right next to README.md. This makes it immediately visible to anyone visiting your project.
Can RapidDev help me set up a changelog workflow for my project?
Yes. RapidDev can set up a changelog workflow including templates, GitHub Release automation, and even a GitHub Action that reminds you to update the changelog with every pull request.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation