How about a changelog?

[Byron]

A sample for non-destructive changelog generation that uses
the git-history as a guide.

It can be filled in manually but will pre-fill itself using
git-conventional commit messages.

It also collects all kinds of interesting information, and
can be customized to not include certain auto-generated sections.

What do you think?

You can play around with it yourself using cargo install cargo-smart-release (a gitoxide project).

[Byron]

I forgot to add the rendered version.

[o2sh]

Great idea! Maybe we should add cargo changelog --write to cd.yml?

[spenserblack]

With a generated changelog, we might want to enforce conventional commits with CI (I swear I've contributed to a repo that did this, but I can't seem to find it). At the very least, maybe strongly encourage the use of the conventional commit format in our contributing guidelines.

[Byron]

@o2sh cargo changelog isn't meant to be fully automatic, it's merely an aid. It can be imagined as building the scaffolding from the commit history, and optional conventional commit messages help to fill in the actual changes. From there a human would polish the descriptions to their liking - they will not be altered by the tool, it's non-destructive.

For the upcoming release, for example, I didn't use conventional commits to flag all fixes - these would have to be added by hand.

@spenserblack Even though I fully understand that thought, I hope with the above explanation it's also understandable why enforcing conventional commits isn't necessary. As a matter of fact, when creating the tool I considered this an anti-pattern. The reason is that this forces one to put considerable effort into classifying commit messages, which is hard to me, which would then potentially spam the changelog and reduce the actual signal.

Thus I write conventional commits only for the purpose of them showing up in the changelog, and not by default. This also means that contributors don't have to change or be aware of anything in regards to commit messages which I find lowers the bar of contributions and makes interactions less cumbersome.

cargo changelog works best in conjunction with cargo smart-release, which will automatically fill in the version of the upcoming commit, but it's strictly optional.

Note that cargo smart-release/changelog were created to allow me manage changelogs of 30'ish interconnected crates in gitoxide along with their versioning to assure I never break anyone while leaving actually helpful changelogs without ever forgetting to put anything there.

It's kind of a lot to take in, if you are interested I can demo it in a call, you can reach me via keybase to set that up.

[Byron]

Now that I know you are interested in adding a changelog, I have put in the time to actually write it beyond the generation of the scaffolding :D. Here is the rendered version.

I have created the upcoming release as a milestone to help me with collecting the tickets involved - generally this is a nice way of preparing a release even if conventional commits aren't always present, like when PRs are merged that typically don't use conventional commits. The Milestone was merely for my own utility, please feel free to close/delete it. It's maybe just me who likes them as I used them extensively over at GitPython.

[spenserblack]

Thanks for explaining! I'm actually a bit relieved to hear that it's not fully automated, as I've always preferred "human-written" changelogs. Mainly because a human is often needed to "squash" changes into a summary.

I also like the idea of milestones. I've only used them for major releases (v1, v2), but I could see us creating next milestones that get renamed once we're confident what the version number should be (I think that's what you're getting at, please let me know if I'm wrong).

How do you see the changelog and release notes working together? Many times notes from one are copied to the other, or the changelog simply says "refer to the release notes," or the release notes say "refer to the changelog." Or do you see the changelog and release notes being different "contexts" with different info?

[Byron]

I also like the idea of milestones. I've only used them for major releases (v1, v2), but I could see us creating next milestones that get renamed once we're confident what the version number should be (I think that's what you're getting at, please let me know if I'm wrong).

For me milestones are just a way to not forget anything that could go into the changelog. Indeed, the version number might not have to be set even since it's not perfectly known - typically I just set it to the next version I predict, often just a patch level.

cargo smart-release also uses commit message analysis to pick the version for you, so feat: … triggers a minor version increment, change!: … would be a breaking change that can trigger a major version change. But that's optional, even though opt-out with cargo smart-release.

How do you see the changelog and release notes working together?

Great question, I forgot to mention that cargo smart-release handles this for you, too. It takes the changelog and processes it into a form suitable for github releases (needs the gh tool with login present), and it creates annotated tags too with yet another form of the changelog to look good there. So if consistency between changelog, github releases and git itself (i.e tags) are desired, cargo smart-release is the easiest way to achieve that. gitoxide relies on that heavily.

[spenserblack]

All sounds good to me! I especially like that git tag annotations are also taken into consideration. It's a personal preference of mine, but I like making/seeing release notes in the repo without needing to open a browser. Maybe onefetch should include some metric on annotated tags 😆

I am curious why you decided that cargo smart-release should execute gh instead of using a library like octocrab, though. Not arguing against the design choice, just curious what the pros are.

[Byron]

Maybe onefetch should include some metric on annotated tags 😆

Don't give me ideas ;).

I am curious why you decided that cargo smart-release should execute gh instead of using a library like octocrab, though.

It was compile/link times and ease-of-use. bat and gh I already know how to use and calling them is trivial (along with detection of their presence). With libraries one usually has to know more to get them to work similarly to their respective CLI tools. I can imagine that as cargo smart-release is used by more parties, it should become more independent and rather use libraries. I think it even shells out a git command to determine the worktree status, it's about time gitoxide learns how to do that 😅.

[spenserblack]

Just stumbled on this app that would allow making milestones with a PR. Since a milestone is being "proposed" in this PR, thought there was a chance that this app would be relevant.

[Byron]

Just checking if there is anything I am missing, but from my point of view there is nothing else to be done here.

Is there anything preventing a merge, is an action required?

Thank you

[o2sh]

Sure! you can merge it. I forgot to approve the PR but it LGTM from the start.
I'll make sure to keep the CHANGELOG.md up to date prior to each release.

Thanks @Byron

[Byron]

Great to hear, thank you!

As this requires a slight change in workflow, let me summarize it here once more. A prerequisite is cargo install cargo-smart-release.

• run cargo changelog --write prior to releasing
• update the changelog and edit what's there at will as long as it is outside of the statistical regions. These are fully generated.
  • note that there are these csr-id-<hash> markers, which can be used to control whether items coming from the git history show or not.
• for fun, you can run cargo changelog --write again to validate that the log is indeed stable and the edits stick like intended. From my experience, this is always the case unless there was some invalid handling of csr-id-<hash> tags which may cause item to re-appear.
• run cargo smart-release (implies dry-run) to see what would happen, or append -e to make it happen. Note that if the gh tool is installed it will create a github release as well that contains the changelog for the new release. If bat is installed it will display the changelog as it would be finalized (it will change the version of the Unreleased section and the date for you).

If there are any problems, as unexpected as it would be, please feel free to reach out.