Page MenuHomePhabricator

Improve API changelog style guide based on feedback and emerging requirements
Closed, ResolvedPublic

Description

The current version of the changelog style guide provides information on how to apply patterns from Keep a Changelog and Common Changelog in API documentation.

This task collects all work related to the changelog style guide improvements resulting from feedback, research into changelog automation, and any emerging requirements.

Plan

  • Improve the style guide based on feedback
  • Investigate opportunities for structuring the changelog and automating changelog publication
  • Identify any internationalization best practices specific to the changelog

Event Timeline

KBach claimed this task.
KBach triaged this task as Medium priority.

I've added a short section about internationalization to the changelog style guide. It links to relevant internationalization resources and highlights key points to keep in mind when preparing on-wiki changelogs for translation.

KBach lowered the priority of this task from Medium to Low.Nov 17 2025, 12:54 PM

Despite our style guide's broad recommendation against it, I (very briefly) looked into changelog automation. The most popular open-source tools for this purpose seem to be: git-cliff, conventional-changelog, and git-chglog. These tools generate changelog content based on git metadata. I tested their outputs using one of my own projects. My main conclusions are:

  • None of the tools provided output that I'd recommend using as changelog content without any edits. However, all the tools generated outputs that I could use as a starting point for my own changelog edits.
  • The quality of the output depended on the quality of commit messages and the use of semantic versioning for all the tools. As expected, main inconsistencies in the output were related to the commit messages, not the tools themselves.
  • git-cliff provided output that would require the least effort to turn into a changelog that meets our style guide recommendations. Its Keep a Changelog template worked well, and I could use the output as a starting point for my own changelog edits.
  • conventional-changelog provided output that was the most complete, but would require significant editing and didn't follow Keep a Changelog recommendations. I imagine that if the commit messages in my project's repository adhered to the Conventional Commit format, the output would be much better. However, some edits would still be necessary.
  • git-chglog produced output that wasn't as useful as the other tools. In my project, its Keep a Changelog template didn't work very well, likely due to inconsistent commit messages.

These conclusions are subjective and the outcome of my tests could be very different for another project. At this stage, I won't be adding any automation-related recommendations to the changelog style guide. If anyone is considering changelog automation in their project, I'd be happy to help make it work.

KBach updated the task description. (Show Details)

No new feedback for the style guide so far. Closing in favor of more specific changes, such as the ones described in T415875.