AZ-400: Designing and Implementing Microsoft DevOps Solutions

Branching Strategies for Source Code

Creating an Effective Change Log

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.

Note

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:

StrategyProsConsExample Tool
Manual entriesHigh accuracy, contextual commentsTime-consuming, error-prone
Automated populationFast, consistent formatMay lack semantic groupingGitHub Actions
Hybrid methodBest of both worldsRequires setup and review processCustom scripts + manual review

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:

ToolDescriptionLink
Standard git logBase command-line history export
gitchangelogGenerates Markdown from git historyhttps://github.com/vaab/gitchangelog
github_changelog_generatorProduces GitHub-style changelogs automaticallyhttps://github.com/skywinder/github-changelog-generator

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:

git log --pretty=format:"%h - %s (%an, %ar)" \
  v1.2.0..v1.3.0 \
  | script-to-format-changelog \
  > projectchangelogs/1.3.0.md
  • --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

Warning

Be mindful of exposing sensitive or internal details in public changelogs. Always review entries before publishing.

Watch Video

Watch video content

Previous
Comparative Analysis Monorepo vs