Discussion: Let's talk about HISTORY.md

[UlisesGascon]

So far, it seems like many packages are using HISTORY.md. I have some questions:

• Do we want to continue doing this?
• Would we prefer to move this information to GitHub releases? This feature didn’t exist back then; it notifies contributors, auto-generates basic information, and allows edits at any time without needing commits/PRs.
• Do we want to keep both (releases and HISTORY.md), as we currently do in Express?

Regardless, if we decide to keep HISTORY.md, we need to define what should be included there, as there’s currently no clear documentation on it, and it’s a manual step prone to errors. For instance, I merged some PRs that didn’t include updates to the file, so I needed to amend them later in the branches, etc.

We stated a discussion last week in the TC meeting and @blakeembrey had a very clear ideas for the future of HISTORY,md.

What do you think?

[ljharb]

CHANGELOG.md is the name I've usually seen most often, and the one I use in my own packages.

I definitely think it makes sense to automate it, if it can be done nicely. I use auto-changelog for this, but it's still not fully ideal.

[bjohansebas]

This should be automated to avoid opening unnecessary PRs for updating the history or delaying the same PRs for something that can be automated. I believe the popular way to do this is by using changesets

[Phillip9587]

I'm in favor of using both the CHANGELOG.md file and GitHub Releases simultaneously. GitHub Releases is a great tool for communicating updates in a way that's visible to contributors and users, making it easy to identify major and minor releases. However, it still has limitations when dealing with a high volume of releases, as paging through many versions can be cumbersome.

A CHANGELOG.md file provides a single, consolidated document where all release notes are organized in one place. This allows users to quickly scan through the history of updates and refer to a searchable file within their development environment, which can be more efficient than navigating multiple release pages on GitHub.

By maintaining both GitHub Releases and a CHANGELOG.md file, we can leverage the benefits of each: GitHub Releases for visibility and announcement purposes, and CHANGELOG.md for an accessible, consolidated history of changes. This dual approach would enhance both the user experience and developer efficiency.

[Phillip9587]

This issue also opens up a discussion about adopting Conventional Commits. By using the Conventional Commits specification, we can clearly identify the nature of each change—whether it’s a new feature, a bug fix, a chore, or something else. This practice can improve clarity in the project’s commit history, making it easier for contributors and maintainers to understand the intent behind each commit at a glance.

Using Conventional Commits could align well with maintaining both CHANGELOG.md and GitHub Releases, as it would add more structure to our release process and ensure that each update is clearly documented and categorized. Moreover, many tools support the Conventional Commits standard and can automate the process of generating the CHANGELOG.md.

[ljharb]

The problem with GitHub Releases is that once you have more than zero of them, tags that lack a release are almost impossible to find. So, it’s either “do a release for every tag, since forever for forever” or “never do a release”.

The problem with conventional commits is that it’s not sufficiently configurable.

[bjohansebas]

Updating the history also causes conflicts with other PRs that are also updating their history for their PR, which blocks the PR until the author fixes it, or if they allow us, we can fix the conflict.

If you want to try automating this, compression could be a good candidate.

[ljharb]

That shouldn’t be much of a problem, and virtually nobody unchecks the “allow edits” checkbox, so a maintainer can always just go update the PR.

[wesleytodd]

We for sure need to automate it, and I agree we should move to CHANGELOG.md. Ideally we would use a release manager like Release Please to do this, which creates GH releases, generates the changelog, and revs the version based on conventional commits. This is the whole package, and would be part of our planned work for the STF grant as well, which should include setting up 2fa as well for these automated releases.