Use https://keepachangelog.com format about craft HOT 11 OPEN

@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

from craft.

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.

from craft.

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

from craft.

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.

from craft.

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

from craft.

the spec always leaves Unreleased at the top

from craft.

@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?

from craft.

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

from craft.

@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.

from craft.

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.

from craft.

@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.

from craft.