# How to Write a Changelog on GitHub - Tool: GitHub - Difficulty: Beginner - Time required: 15 minutes - Compatibility: Any modern web browser — GitHub Free plan and above - Last updated: March 2026 ## TL;DR 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. ## Before you start - 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 ### 1. 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. ### 2. 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. ### 3. 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. ### 4. 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. ### 5. 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. ### 6. 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 code example File: `CHANGELOG.md` ```markdown # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). ## [1.1.0] - 2026-03-28 ### Added - User profile page with avatar upload - Email notification preferences in settings - Export data to CSV from the dashboard ### Changed - Improved loading speed on the dashboard by 40% - Updated Supabase client library to latest version ### Fixed - Fixed login redirect loop on Safari browsers - Fixed date picker not showing correct timezone ## [1.0.0] - 2026-03-15 ### Added - Initial release with user authentication - Dashboard with real-time data visualization - Settings page for account management - Responsive design for mobile devices ``` ## Common mistakes - **Writing vague entries like "Updated stuff" or "Bug fixes"** — undefined Fix: Be specific. Write "Fixed checkout page crashing when cart is empty" instead of "Bug fixes." Users need to know exactly what changed. - **Not using a consistent date format** — undefined Fix: Always use YYYY-MM-DD (like 2026-03-28). Avoid formats like March 28th or 28/03/2026 which are ambiguous across countries. - **Putting the oldest version at the top** — undefined Fix: Changelogs should be in reverse chronological order — newest version first. This way visitors immediately see the latest changes. - **Forgetting to update the changelog when making changes** — undefined Fix: 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 ## 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. --- Source: https://www.rapidevelopers.com/github-for-non-tech/how-to-write-a-changelog-on-github © RapidDev — https://www.rapidevelopers.com/github-for-non-tech/how-to-write-a-changelog-on-github