How to generate detailed release notes?

[jbcpollak]

I was researching how the release notes for msw look and how we could to something similar in our org, and I noticed some of the notes for msw@v0.44.0: https://github.com/mswjs/msw/releases/tag/v0.44.0 don't match their respective commits:

• how was the bulleted list for adhere to Fetch API "Request" in response resolver created? It doesn't match the relevant commit.
• the text in the release notes for this commit doesn't quite match the commit message itself.

Are the release notes manually massaged after creation?

[kettanaito]

Hey, @jbcpollak. I really appreciate you asking so many questions!

I edit some MSW releases manually from time to time to provide additional detail. The Release tool doesn't facilitate detailed release notes as it only lists the conventional commit messages and the GitHub references they related to. That being said, I'd love to change that.

One thing I've added recently is that commit bodies will be rendered below the respective commits in the release notes (see this). This way you can write a detailed list like I did in "Adhere to Fetch API" in the commit body, which should get it rendered in the release notes markdown.

# commit example
feat: support graphql

- Migrates to X to enable Y;
- Deprecates `Z`. Please prefer using `A`.

Do you have any ideas how we can improve on this? Maybe you have some release notes format in mind, please share that. Thanks.

[jbcpollak]

I think it makes sense to edit the release notes after the fact, though I also think that feature you just added may go a long way to minimizing that need. It looks like it only triggers on breaking changes - we might want it on all notes or possibly just features. I know you want to minimize configuration, and different teams use commit messages differently - maybe there's another keyword that could be added to the summary to trigger notes?

Our process works like this:

• devs work on features on branches and can use any commit messages they want, we don't validate them at commit time.
• the summary of the PR must be in conventional-commit format
• we use a bot which we trigger by commenting /mergeit to merge the PR to main. This bot automatically puts the summary of the PR in as the commit message for the merge. We could modify the bot to pull additional release notes from the description of the PR and add that in the notes section, which could trigger the above functionality you have.
  • I actually hate having to use the bot, but its the only way I've found to enforce the commit message at the PR level, and we want to maintain a 1:1:1 mapping between PRs, issues and release note bullets.

I think the only thing blocking us from using release in this context is the requirement to to use breaking whenever we want notes added.