Automated release changelog

[ang-zeyu]

Filler issue for project board sticking.

Ups for research / discussion 😀

[tlylt]

If I may chip in 😅 (for discussion)

I recently explored using semantic-release with commitizen, as shared in a course by Kent C. Dodds and found the releasing workflow to be very manageable (together with the use of github action to automate it). It generates a changelog based on the commit messages. Example from my sample project:

Not too sure how well it plays with lerna though.

[ang-zeyu]

Sounds interesting! I would be ok with imposing the conventional commits spec here as well since its rather well known.

Not too sure how well it plays with lerna though.

Wonder if there's a lighter weight package / option inside to generate just the changelog, I think we would want to stick with one tool for managing packages / dependencies in general to avoid possible dependency issues / differences

[tlylt]

Thought this might be helpful https://github.com/release-drafter/release-drafter

• will automate some parts of the release note based on the custom-defined template
• make release less painful by working on the draft and updating as PRs are merged in

[tlylt]

Thought this might be helpful release-drafter/release-drafter

• will automate some parts of the release note based on the custom-defined template
• make release less painful by working on the draft and updating as PRs are merged in

Hi @jonahtanjz, I thought it might be a good time to bump this:) Wonder if you think we should try using the above-mentioned action to help with our release workflow? (Given that you just did a release yesterday, do you think this will be helpful?)

[jonahtanjz]

@tlylt Sure this would definitely be helpful in keeping track of the changelog as PRs are merged instead of consolidating it at each release. We can try it out first for the next release and see how it goes :)

[tlylt]

@tlylt Sure this would definitely be helpful in keeping track of the changelog as PRs are merged instead of consolidating it at each release. We can try it out first for the next release and see how it goes :)

Okay I have experimented with the release-drafter action a little, and here's my finding/plan moving forward: (@MarkBind/active-devs seeking comments/suggestions before I put up a PR):

Release-drafter action will be used to help automate part of the release process. It can

• Automatically categorize PRs and populate the release draft with PR title, PR number & link, as well as the contributor name (Manual labeling needed)
• Automatically calculate the next release version number based on semver (Manual labeling needed)

To help with the above, maintainers need to ensure that before merging a PR:

• It has a correct label describing what change it belongs to, i.e. labelling the PR with 'a-Documentation 📝' if it is a documentation change. Multiple labels can be used (this means this PR will be included in multiple categories). If there's no suitable label, not labeling it is still fine, as it will still be included in the draft, under "### Miscellaneous". The label to category mapping is controlled by us, within the config:

• It has a correct version label (either major, minor, patch, will need to create these labels later). The rule is such that within a release, the GitHub action is smart enough to use the maximum level of the label to determine the release version, which will be reflected in the release title)

Finally before an actual release:

• The maintainer may want to look through the release draft, ensure that the tag is correct, include details about PRs that have breaking changes, and shift the categories under "User Facing Changes" or "Other Changes". and finally hit release:)

Some notes on the release action's behavior:

• On push to master (after a PR merge, or after direct commits), the release-drafter action will be triggered and it repopulates the current draft release (creates a new draft if it doesn't exist yet) based on the configuration and the PR info. This means it's not recommended to make any custom changes to the release draft before the actual release, because it may get overridden if there's a new push to master. On the other hand, it means for all the PRs yet to be released, we can still append labels to them and as long as we rerun the action manually, the release draft can pick up the changes and update accordingly.

A related change that I intend to propose:

• Include a "proposed release note on breaking changes" section in our PR template, so that we can draft up the relevant details about a breaking change PR when it is done, instead of doing it at the end when we are releasing it. To reduce the workload on the PR creator, we can perhaps mark this as optional for the PR creator to do, but it must be filled by the maintainer who merges the PR in.

[ong6]

Okay I have experimented with the release-drafter action a little, and here's my finding/plan moving forward: (@MarkBind/active-devs seeking comments/suggestions before I put up a PR):

LGTM! From what I understand this would make showing the change log of breaking changes much simpler.

A few questions I have are:

1. Having the PR in multiple categories can be quite confusing and unnecessary. Is there a way to ignore anything thats not in XXX category?
2. Does this work better than Github's built in releases and is it easy to configure (since that may be simpler to use and easier to configure)

[tlylt]

1. Having the PR in multiple categories can be quite confusing and unnecessary. Is there a way to ignore anything thats not in XXX category?

This is totally up to us, so if we don't want to put them in multiple categories, we can simply label the PR with one category related label.

2. Does this work better than Github's built in releases and is it easy to configure (since that may be simpler to use and easier to configure)

Seems like GitHub's default release note has a way to configure and do something similar, such as categorizing PRs base on labels, but it lacks additional functionality (eg resolving version) that are provided by the GitHub Action. I think either is fine for the task of helping to categorize PRs by label

[ong6]

@tlylt Very nice, I think we can try release drafter then!

[raysonkoh]

I think this tool looks very promising and if it can make the release process simpler we should definitely give it a try.

I'm curious how does the release drafter know which PRs to choose for the next release? Does it choose it based on the milestone assigned to the PR or it just accumulates all the PRs that have been merged since the last release?

Also is there any flexibility in modifying the semver version that it calculates?

[tlylt]

I'm curious how does the release drafter know which PRs to choose for the next release? Does it choose it based on the milestone assigned to the PR or it just accumulates all the PRs that have been merged since the last release?

Hmm, are you saying you want to cherry pick some merged PRs to form a release? I think at the moment what we have here is that all PRs yet to be released will be included in the release, and we are drafting for just the next release (so just one release). Could be possible by configuring the tool, but I'm not sure if we are going to draft multiple pending releases.

Also is there any flexibility in modifying the semver version that it calculates?

If we need to tweak the final version, just edit the release note. The release will be a draft so it's not public.

[raysonkoh]

Hmm, are you saying you want to cherry pick some merged PRs to form a release?

Yes I was thinking about multiple pending releases. Would be good if the tool can support this, but not an issue for now as you mentioned.

If we need to tweak the final version, just edit the release note.

Great 👍

[ang-zeyu]

Should this be closed for now? (https://github.com/MarkBind/markbind/pull/2172#issuecomment-1472225940)