Project Files

Written & tested for accuracy by a developer (not AI) · Updated November 2026

What Is a Changelog?

What is the CHANGELOG.md file. It lists a project's notable changes, in chronological order. Here's how it differs from a Git log and release notes, and why AI agents use one.

A changelog tells you what changed in a project, and when, in a list you can read quickly. It is usually a file named CHANGELOG.md in the project's top folder.

Typically, a project's history is managed with Git version control, which records every change in project snapshots, when you save with "commits" as you work. Experienced developers also keep a changelog, a short dated list of the changes that matter. When an AI agent works on your project, that list is how the next session (and you, next month) learns what has already been done. For a small project you'll finish this week, Git's history may be all you need.

What's in a Project Folder? explains the other files you'll find beside a changelog in a project. Project files such as the changelog come up as soon as you start coding, which is one step in the complete Mac setup checklist.

What goes in a changelog

The best-known format is Keep a Changelog, which describes a changelog as a curated, chronological list of the notable changes in each version of a project. Here's what it recommends:

  • Newest first - the latest version is at the top, so a reader sees the recent changes without scrolling.
  • A date for each version - written as year, month, and day, such as 2026-11-04.
  • Changes grouped by kind - under six headings: Added, Changed, Deprecated, Removed, Fixed, and Security.
  • An Unreleased section - at the top, collecting changes as they are made, until the next version is released.

Some projects use another name for the file, such as HISTORY, NEWS, or RELEASES, but CHANGELOG.md is the most common.

Changelog example

Here's a short CHANGELOG.md in the Keep a Changelog format:

# Changelog

## [Unreleased]

### Added
- A search box on the recipes page.

## [1.1.0] - 2026-10-28

### Added
- A shopping list for each recipe.

### Fixed
- Photos no longer stretch on narrow screens.

## [1.0.0] - 2026-09-15

### Added
- The first version of the recipe website.

Each entry is one line a reader can understand without looking at the code. One entry often covers several commits.

Version numbers

The numbers in the example follow Semantic Versioning, written as MAJOR.MINOR.PATCH. The first number goes up for a change that breaks compatibility with earlier versions, the second for a new feature that keeps compatibility, and the third for a bug fix. A version that starts with 0, such as 0.3.1, means anything may still change.

Many projects never make a release, such as a personal project or an AI-assisted project that changes every day. For those, use dates as the headings in place of version numbers. The layouts in Spec-Driven Development for AI describe the changelog this way, as notable changes, dated, newest first.

Changelog, Git log, and release notes

Three records of a project's changes are easy to mix up:

  • Git's commit log - every step, recorded as you work. Keep a Changelog points out that a commit log is noisy, with merge commits, unclear titles, and small fixes, so it doesn't make a good changelog.
  • The changelog - the notable changes, chosen and written for a reader, in a file in the project.
  • Release notes - what a project publishes about one release. On GitHub, a release is tied to a Git tag (a label that marks one point in the project's history). Its notes are written by hand or generated by GitHub.

To see a project's commit log, open a terminal application and move into the project folder. This command shows one line for each commit, newest first:

$ git log --oneline

Some projects keep their release notes on GitHub and skip the file. If you've installed Homebrew, its CHANGELOG.md (in /opt/homebrew on a Mac with Apple Silicon) is two lines that point to Homebrew's releases on GitHub. Keep a Changelog prefers a file, because GitHub's releases appear only on GitHub and are harder to find.

You may also see commit messages that start with feat: or fix:. That convention, Conventional Commits, lets a tool write a changelog from the commit messages. Keep a Changelog prefers a changelog written for people.

How to open a changelog on Mac

A CHANGELOG.md is a Markdown file, the same kind as a README, so What Is a README File? explains how to open it. Select it in the Finder and press Space to see it in Quick Look as plain text, or open it in a Markdown editor to see it formatted.

Git keeps the commit log itself in a hidden .git folder in the project. Show Hidden Files on Mac shows how to see it, but leave that folder alone, because Git manages it.

Changelogs and AI agents

An AI agent forgets almost everything between sessions. Git's history is available to it, but its details are limited, so a changelog gives the next session, or a different AI agent, a readable account of what changed and when.

I recommend asking an AI agent to keep a changelog. Anthropic Claude or ChatGPT Codex can write each entry when you finish a piece of work. Add a rule to your AGENTS.md file that tells the AI agent to ask whether you want a changelog entry every time you say you're finished with a work session (Agent Instructions explains that file). Starter Projects shows how a changelog and a work ledger of handoff notes give an AI agent a memory of the project.

Now you can read any project's changelog, tell it apart from Git's log and release notes, and keep one so you and an AI agent can pick up where you left off.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.