Use https://keepachangelog.com format

[armcknight]

I think this is the line that replaces the ## Unreleased header to ## <version-number for a release: https://github.com/getsentry/craft/blob/2e4f74c618ce99c184d4a4643fd92abda5ad0724/src/commands/prepare.ts#L399

Two proposals to improve our workflow here:

1. Instead of replacing ## Unreleased, simply insert \n\n## <version-number> beneath it, so the unreleased section is there waiting for when we want to add more things during development, instead of having to rewrite that after every release.
2. To adhere more closely to the https://keepachangelog.com format (because we are about 95% of the way there), we should include the date of the release and enclose the formats in square brackets, as such:

[asottile-sentry]

duplicate of #415 -- there's additional discussion there about why such a format is undesirable

[armcknight]

That duplicates one of my points, but not the other. I brought up keepachangelog in slack in the past and there was some interest in it, and it's worth noting that the spec always leaves Unreleased at the top. You should reopen this issue for feedback from the community @asottile-sentry. If anything, close the other one as a duplicate as it is a subset of this one.

[asottile-sentry]

I'd recommend splitting the two concerns then -- make this one just about the changelog format and the other about the "unreleased at top" -- coupling the two is a little counter-productive

[armcknight]

the spec always leaves Unreleased at the top

[BYK]

@armcknight repeating my question from #415, why not go with the fully automated changelog approach so you don't even need the # Unreleased part and all the dance around that?

[brustolin]

What will happen when we release the new version? Will Changelog have an empty unreleased section? This I don't like.

[armcknight]

@BYK I’m afraid this might have me out of my depth w.r.t. craft, is that something that craft does to e.g. pull commit messages since the last release and populate the changelog that way? I’d certainly be ok with that as an option, but I could see also how some folks might want to have different wording for their changelog entries, if for no other reason than to be able to write entries longer than the recommended 72 char max for commit messages. It would also avoid things like revert commits slipping in or other commits that shouldn’t be user-facing.

@brustolin yes, it would. I’m only recommending adhering to a standard spec, I don’t have any opinion on this other than to provide people with what they might be used to already in other places that use this spec. FWIW I’ve written automation in the past to pull just the pertinent portion of the changelog out to add to a git tag’s comment and the GitHub release page, so it wouldn’t be visible there, but would be in the full changelog. There’s also a bunch of similar tooling out there, although of course we’d probably roll out own.

[BYK]

@armcknight It does much more than that if you are willing to use it. Here's a good example: https://github.com/getsentry/craft/releases/tag/0.25.0 -- It uses GitHub milestones to group PRs and use a better wording and sectioning for a feature. Some more docs here: https://github.com/getsentry/craft#changelog-policies

[armcknight]

Thanks for the info and link @BYK, that's good stuff. Looks like my first point would apply here, to change this

Else if there is an entry named Unreleased, rename that to the given version

to "insert version heading beneath". I think everything else would still work as is, after modifying the format per my point 2.

[BYK]

@armcknight the thing I was trying to point at was, if you were to use fully automated changelogs, the need for the Unreleased section vanishes as there won't be anyone adding manual changelog content or entries into the file manually.

[armcknight]

Understood @BYK. I was only pointing out the need for my proposed change if, for whatever reason, people don't want to use the automated changelog feature.