Maintain a semantic changelog #189
Labels
Issue-Enhancement
The issue is a feature or idea
Comments
michaeltlombardi
added a commit
to michaeltlombardi/DSC
that referenced
this issue
Sep 7, 2023
Prior to this change, the project didn't maintain a changelog file. Instead, it relied on generation of release notes from PRs. As raised in PowerShell#189, the auto-generated changelog is limited in its effectiveness for changelog readers outside of the maintenance team. The entries depend entirely on the PR titles, they aren't organized by kind or relative importance, and they can't link to documentation. This change: - Defines the changelog by hand, adhering to the KAC format with an extension for how related work items are displayed, using a details element to collapse them. - Fully documents the set of user-facing changes that are included in the `alpha.2` release, including summaries and related work items and linking to documentation where appropriate. - Resolves PowerShell#189
github-merge-queue bot
pushed a commit
that referenced
this issue
Sep 8, 2023
(GH-189) Add semantic changelog
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Summary of the new feature / enhancement
In the current release model, there's a single set of release notes for each tag of the project. These release notes include maintenance changes, bug fixes, documentation updates, and new features in a way that requires me to parse the full set of notes to understand what changes are important to me. Because the entries are pulled from the PR titles, I also usually need to follow the links to the PRs and often the issues those PRs relate to in order to get the full context.
Proposed technical implementation details (optional)
Keep a semantic changelog for the project that breaks down changes to each version across the kind of change. Write the changelog entries for non-maintainers - resource authors, end users, and integrating vendors in particular - and link to the documentation for new features or changes as well as the relevant PRs and issues.
Consider this comparison between the auto-generated release notes and an intentionally crafted changelog for
alpha.2:Considerations
At first glance, maintaining a high-quality changelog is substantial effort compared to just relying on the auto-generation for the release notes. I think there's a way forward that uses a combination of auto-generation and hand-crafting for this purpose, such as a transformer over YAML data, which I'd be happy to investigate and prototype for the team.
My primary concern is that end users, resource authors, and integrating developers have a useful document that describes the changes in a release. In the short term, I'd be happy to fully hand-craft this document.
In my experience, there are a few concerns that get brought up when discussing maintaining a changelog by hand instead of using automated tooling:
It requires more work.
In my experience, this only applies when the existing entries aren't very useful. There are changelog tools that generate the semantic structure and entries using a combination of PR titles and labels. In those cases, the work is actually the same - you need to write your PRs like changelog entries and remember to label your PRs appropriately. This is fundamentally the same work as adding a list item in the correct section of the changelog.
Writing and reviewing the changelog at release time is error prone.
I agree with this entirely. One common solution to this problem is to maintain an Unreleased section at the top of the changelog that accumulates every change since the last version. This serves a few purposes. It ensures that changelog entries are written and updated as close to the implementation of the change as possible, meaning everyone working on the changelog has the freshest and most accurate perspective on the change that they're going to have. From that point on, our memories of the change and context only degrade with time. It also enables curious readers to check the changelog for how the next release will affect them, giving them an opportunity to file work items for themselves or the team before the code ships in a release.
It can lead to merge conflicts when two PRs both modify the same section of the changelog and are merged near the same time.
There's not really a good way around this, except to be nindful that addressing the conflict may require rebasing and a bit of work, but adjusting changelog entries is never as complicated as addressing merge conflicts for code in my experience.
Beyond those points, auto-generated changelogs that rely on PRs to build the changelog have a few pitfalls that I think are fundamental issues:
Pull Requests are maintainer-facing documentation, not user, author, or integrating vendor documentation. Pull requests are about the internal context leading to a change. The title and body of a PR are intended to provide context to the reviewers and maintainers of the repository. That context is not always parseable for external folks, especially general users. When we conflate maintainer-facing documentation with external-facing documentation, we need to make compromises for one group or the other.
When changelogs are generated from pull requests, we only get one entry in the changelog per PR. This means that either:
One solution to this problem is to require PRs to be fully atomic: each PR only makes exactly one external-facing change that would merit a changelog entry. This vastly increases the overhead for maintainers and contributors, requiring folks to split PRs or accept the flattening of the changelog or release notes.
When changelogs are generated from pull requests directly, the only documentation we can associate with those entries is the PR (maintainer facing documentation) and related issues (contextual to why the change happened but not necessarily descriptive of how the change affects the project).
The text was updated successfully, but these errors were encountered: