Skip to main content
An up-to-date changelog is essential for tracking a project’s evolution, communicating new features, fixes, and deprecations. By following best practices, you ensure that contributors, stakeholders, and end users can quickly understand what’s changed between releases.
The image outlines the purpose of a change log, highlighting three key aspects: addition of new features, modifications to existing features, and deletion of outdated features.

​
1. Key Principles for a Maintainable Changelog

​
1.1 Clarity Over Quantity

Focus on concise, relevant entries. Avoid verbose descriptions—each item should add clear value so readers can scan updates efficiently.
A streamlined changelog encourages adoption and reduces confusion. Keep each bullet to one idea and link to detailed issues or PRs when needed.

​
2. Changelog Generation Strategies

Choose an approach that fits your team’s workflow and project size. Below is a comparison of the three most common methods:
The image outlines three strategies for change log generation: manual entries for clarity, automated population for efficiency, and hybrid methods combining automation with oversight.

​
3. Essential Tools to Assist

There are several popular utilities designed to simplify changelog maintenance:
The image is a slide titled "Tools to Assist," featuring two numbered sections: one about using the standard git log for command-line entries, and another about using gitchangelog and github_changelog_generator for automated solutions.

​
3.1 Practical Example: Customizing git log Output

Below is a sample Bash command to extract commits between two tags, format the output, and save it as a Markdown file:
  • --pretty=format:"%h - %s (%an, %ar)"
    • %h : abbreviated commit hash
    • %s : commit message
    • %an: author name
    • %ar: author date, relative
  • v1.2.0..v1.3.0 specifies the tag range to compare
  • script-to-format-changelog represents your custom formatting script
  • Redirect output into projectchangelogs/1.3.0.md for Markdown storage
Be mindful of exposing sensitive or internal details in public changelogs. Always review entries before publishing.

Watch Video