Automating Release Notes from Merged PRs: A Practical Guide

As engineers, we love building things. What we often don't love is the administrative overhead that comes with shipping them. Among the most common culprits is writing release notes. It's a task that often falls to the last minute, becomes a scramble to remember what changed, and frequently results in vague, incomplete, or inconsistent updates. You know the drill: sifting through Git logs, trying to decipher cryptic commit messages, and manually compiling a list of changes that hopefully makes sense to your users or stakeholders.

But what if there was a better way? What if the very process you already use to merge code – your Pull Requests (PRs) – could automatically become the source of truth for your release notes? This isn't just a pipe dream; it's a practical strategy that leverages existing workflows to generate accurate, timely, and user-friendly changelogs.

Why Merged PRs Are Your Best Bet for Release Notes

Think about your typical development workflow. You branch off, implement a feature or fix a bug, and then open a Pull Request. This PR isn't just a code review mechanism; it's a discrete unit of work, often tied to a specific issue or user story. It represents a completed, reviewed, and approved change ready for integration.

Here's why PRs are an excellent foundation for release notes:

  • They encapsulate a single logical change: Unlike individual commits (which can be numerous and granular for a single feature), a PR usually represents one complete, shippable improvement or fix.
  • They come with context: A good PR has a title, a description, and sometimes labels. This metadata is invaluable for understanding the what and why of a change, which is exactly what your users want to know.
  • They're already part of your workflow: Your team already creates, reviews, and merges PRs. You're not adding a new step; you're leveraging an existing one.
  • They're often linked to issues: Many teams link PRs to Jira tickets, GitHub Issues, or similar, providing a direct trail to the original problem or requirement.

Contrast this with trying to derive release notes purely from Git commit messages. While tools like git log are powerful, commit messages can be notoriously inconsistent, too technical, or simply not user-friendly. A PR, by its nature, encourages a higher-level summary of the work.

The Manual Release Note Grind: A Familiar Pain

Before we dive into automation, let's acknowledge the current state for many teams. The manual process often looks like this:

  1. Identify the release scope: Determine which commits or PRs are part of the upcoming release, usually by comparing two Git tags or branches.
  2. Scrape the history: Use git log or browse your Git provider's UI.
  3. Filter and interpret: Try to distinguish between internal-only changes (refactors, CI updates) and user-facing features or fixes.
  4. Translate: Convert technical descriptions into something understandable by non-engineers.
  5. Format: Manually write out the changelog in Markdown, HTML, or plain text, often categorizing items.
  6. Review and iterate: Get feedback, fix omissions, and correct inaccuracies.

This process is tedious, error-prone, and a significant time sink. It often delays releases and can lead to important changes being missed, or worse, incorrect information being published.

The Core Idea: Programmatic Extraction of PR Data

The first step to automating release notes is to programmatically extract the relevant information from your merged PRs. What data points are most useful?

  • PR Title: Often a concise summary of the change.
  • PR Body/Description: Provides deeper context, motivation, and potential impact.
  • Labels: Categorize the change (e.g., feature, bug, chore, enhancement).
  • Author: For giving credit where credit is due.
  • PR URL: A direct link back to the source of truth for more details.
  • Associated Issues: Links to Jira, GitHub Issues, etc., for full traceability.
  • Merge Date: To group changes by release timeframe.

Automating the Extraction: A DIY Approach and Its Pitfalls

You could build a custom script to do this. Most Git providers offer robust APIs for interacting with their platforms. Let's consider GitHub as a concrete example.

You can use the GitHub API or its excellent gh CLI tool to fetch merged PRs. For instance, to get all closed PRs merged between two dates for a specific repository:

gh pr list --repo your-org/your-repo --state closed --json number,title,body,labels,url,author,mergedAt --search "merged:2023-01-01..2023-03-31" > prs.json

This command fetches a list of PRs within a specified date range and outputs their number, title, body, labels, URL, author, and merge timestamp in JSON format. You could then parse this prs.json file using a tool like jq or a Python script:

# Example using jq to extract titles and labels
jq -r '.[] | "PR #\(.number): \(.title) [\(.labels | map(.name) | join(", "))]"' prs.json

A Python script would give you more flexibility to process the data:

```python import json

def generate_release_notes(prs_data): features = [] bug_fixes = [] chores = []

for pr in prs_data:
    title = pr['title']
    url = pr['url']
    labels = [label['name'].lower() for label in