From Conventional Commits to LLM-Generated Release Notes

- 5 minutes read - 935 words

Introduction

For several years, I adopted Conventional Commits across my software projects. The premise was straightforward: write commit messages in a structured, machine-readable format, then leverage tooling to generate changelogs and release notes automatically.

For example:

feat: add user login
fix: resolve payment retry issue
docs: update API usage guide

This approach served me well. Tools like Conventional Changelog could parse commit history and produce structured release notes with minimal manual effort. For years, I considered this the standard practice — the best we could do.

The Conventional Commits Era

Conventional Commits brought discipline to commit messages. Instead of vague entries like:

update code
fix bug
change stuff

developers could write messages that were both meaningful to humans and parseable by machines:

feat(payment): support offline transaction queue
fix(auth): handle expired refresh token correctly
refactor(api): simplify error handling

This structure enabled automation. Release notes could be grouped by type — features, bug fixes, refactoring, documentation updates, and breaking changes — reducing manual effort and making the release process more consistent across engineering teams.

The Limitation

Despite these benefits, Conventional Commits remain heavily dependent on the quality of individual commit messages. A terse commit produces a terse changelog:

fix: update validation

This tells the reader almost nothing. What validation was corrected? Why did it matter? Who is affected? Is any migration required?

Traditional changelog tools can format commit messages elegantly, but they lack the ability to infer the deeper context behind a change. They excel at structure but fall short on explanation.

A New Perspective

Recently, while researching how LLMs could be applied to technical documentation, I came across SmartNote — a research project from Peking University’s OSSLab that uses LLMs to generate thorough, context-rich release notes from pull requests and commit data.

That discovery prompted me to reconsider the entire release-notes pipeline. If an LLM can synthesize raw development artefacts into coherent, detailed notes, then perhaps release notes should be more than a formatted dump of commit messages. Perhaps they can be substantially better.

How LLMs Transform Release Notes

LLMs fundamentally change what is possible in documentation generation. Rather than merely converting commit messages into a changelog, an LLM can help articulate:

  • what changed

  • why it changed

  • how it affects users

  • what developers need to know

  • whether there are breaking changes

  • what migration steps are required

  • what risks or limitations exist

The difference is substantial. Consider a conventional changelog entry:

feat: add batch payment support

An LLM-generated release note, by contrast, could read:

This release introduces batch payment support, enabling users to submit
multiple payment instructions in a single request. This reduces manual
operations and improves processing efficiency for high-volume payment
scenarios.

Developers should review the new batch payment API contract and ensure
proper error handling for partial failures.

The second version delivers far more value to product users, developers, support teams, and stakeholders alike.

Conventional Commits Are Still Valuable

This does not mean Conventional Commits are obsolete. On the contrary, they remain highly useful. Structured commits provide a strong input signal for automation, helping the LLM understand the type and scope of each change.

A future-oriented workflow might look like this:

SmartNote Pipeline

In this model, Conventional Commits are not the final output — they become one important input to a smarter, LLM-driven release-note generation process.

From Changelog to Communication

A traditional changelog is typically written for developers. Release notes, however, should be written for people — a broad audience that includes:

  • developers

  • product managers

  • support engineers

  • business stakeholders

  • end users

Each audience has different needs. A developer cares about APIs, configuration changes, and migration paths. A business stakeholder cares about value, risk, and impact. An end user simply wants to know what is new and how it benefits them.

LLMs excel here because they can transform the same set of technical changes into multiple versions of release notes, each tailored to a different audience.

A Better Release Notes Workflow

A modern, LLM-based release notes workflow could include the following steps:

  1. Collect commits, pull requests, issues, and code diffs.

  2. Ask the LLM to group changes by theme.

  3. Generate a user-friendly summary.

  4. Generate a developer-focused technical section.

  5. Detect possible breaking changes.

  6. Add migration notes where applicable.

  7. Let humans review and refine the final result.

This approach combines automation with human judgement: the LLM handles the heavy drafting, while the team retains ownership of the final message.

Tools like SmartNote go further by generating release notes personalised to your project domain and audience type.

My Current Thinking

Several years ago, I believed that Conventional Commits paired with Conventional Changelog represented the best practice for release-note generation. Today, I see them as one part of a larger solution.

LLMs make it possible to generate release notes that are more complete, more readable, and more useful than what structured commits alone can produce.

The status quo is shifting. Tools like SmartNote demonstrate one promising direction; tomorrow, better options will inevitably emerge. The important insight is not any single tool — it is the transition itself:

From structured commit messages
to intelligent release communication.

Conclusion

Conventional Commits helped teams standardise commit messages and automate changelog generation. That was a meaningful step forward.

But LLMs have raised the bar. Release notes no longer need to be thin summaries of commit messages. They can become thoughtful explanations of product change, technical impact, and user value.

Conventional Commits were the foundation. LLM-generated release notes may well be the next layer. And as better tools continue to emerge, the way we write changelogs and release notes will keep evolving.

References

comments powered by Disqus