The Friday Afternoon Changelog Problem

It is 4:00 PM on a Friday. The deployment pipeline just finished running, the tests passed, and the new version of your application is live. Now, someone has to tell the customers what actually changed.

You open your terminal and run git log.

What you see is a list of commits that look like this: fix: typo in config, wip, Merge branch 'hotfix/auth-bug', and Update dependency version.

None of this means anything to a user.

The engineering work is done, but the communication work is just starting. This is the moment where most teams fall back on manual labor: someone reads through the commits, tries to remember what hotfix/auth-bug actually fixed, and writes a summary by hand. It takes hours. It is tedious. And it is the reason why release notes are often delayed, incomplete, or simply skipped.

We know we need to automate this. The question is how.

How We Usually Do This (And Why It Hurts)

The first instinct is to just use the tools we already have. Bitbucket has a REST API that lets you pull commits for a specific repository and revision range.

You can write a script that grabs all the commits since the last tag, formats them into a markdown list, and calls it a changelog.

The output looks exactly like the git log you stared at earlier. It is a list of engineering tasks, not a summary of customer value. Commit messages record brief technical details of a unit of work; they are written for other developers, not for users.

When you expose raw commits to customers, you are forcing them to translate engineering-speak into product features. They will not do it. They will just stop reading.

The Pipeline Script That Almost Works

The next step up is filtering. If we can't show them everything, maybe we can just show them the important things.

This is where Conventional Commits come in. By enforcing a prefix on every commit message—like feat: for new features or fix: for bug fixes—you can write a Bitbucket Pipeline that only extracts the commits that matter.

Your bitbucket-pipelines.yml might include a step that looks like this:

- step:
    name: Generate Release Notes
    script:
      - echo "## Features" > RELEASE_NOTES.md
      - git log --since=$LAST_TAG --pretty=format:"- %s" | grep "^feat:" >> RELEASE_NOTES.md

This is better. It categorizes the changes. It filters out the chore: and ci: commits that users don't care about.

But it still relies on the developer writing a commit message that makes sense to a non-technical reader. And developers, generally speaking, do not want to do that. They want to write feat: add support for new auth provider and move on.

The Problem With Your Commits

The core tension here is that commit messages and release notes serve two different audiences.

Commits are for your future self and your colleagues. They need to explain why a technical decision was made. Release notes are for your users. They need to explain what the new behavior is and how it affects them.

You can try to enforce strict commit hygiene. You can require every feat: commit to include a user-facing description in the body. But this is a cultural problem, not a technical one. It requires constant vigilance and code review pushback just to maintain the quality of the changelog.

A 2023 study on commit message quality found that low-quality commit messages impede comprehension, and that overall quality tends to decrease over time.

If your commits are messy, your automated release notes will be messy.

The Translation Layer

This is the point where teams usually give up on automation and go back to writing release notes by hand.

But there is a third option. If the problem is translation—turning engineering artifacts into customer language—then we need a system that can translate.

Recent approaches use Large Language Models (LLMs) to interpret unstructured or semi-structured commits and generate summaries in customer language. The AI layer can infer intent from commit diffs, group related changes, and rephrase technical language.

You can feed a list of raw commits into an LLM and ask it to generate a clear, relevant release note. Microsoft's GenAIScript demonstrates exactly this approach, pulling commit history and diffs and passing them to a model with a prompt that instructs it to tell a story about the changes.

This solves the translation problem without requiring perfectly formatted commits. It takes the feat: add support for new auth provider and turns it into "You can now log in using your Google account."

But unmanaged AI fails. If you just pipe the output of an LLM directly to your documentation site, you will eventually publish a hallucination or miss a critical breaking change. AI needs human governance to maintain architectural coherence.

The successful operational model is a hybrid one. The AI drafts the release notes directly from the code commits. A senior writer or product manager reviews the draft in a dashboard, checking for accuracy and tone. Edge cases are flagged. Patterns are fed back into the system to improve the next run.

This is what Doc Holiday does. It is a documentation engine that generates output directly from engineering workflows, including Bitbucket commits. It provides the structure for lean teams to validate, manage, and scale their output. It takes the raw artifacts of your deployment and gives you a drafted, categorized, and translated release note, ready for human review.

It turns the Friday afternoon scramble into a quick approval process.