Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use https://keepachangelog.com format #422

Open
armcknight opened this issue Oct 14, 2022 · 11 comments
Open

Use https://keepachangelog.com format #422

armcknight opened this issue Oct 14, 2022 · 11 comments

Comments

@armcknight
Copy link
Member

I think this is the line that replaces the ## Unreleased header to ## <version-number for a release:

replaceSection = changeset.name;

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:

image

@asottile-sentry
Copy link
Member

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

@armcknight
Copy link
Member Author

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
Copy link
Member

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
Copy link
Member Author

the spec always leaves Unreleased at the top

@BYK
Copy link
Member

BYK commented Oct 16, 2022

@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
Copy link
Contributor

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

@armcknight
Copy link
Member Author

armcknight commented Oct 17, 2022

@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
Copy link
Member

BYK commented Oct 17, 2022

@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
Copy link
Member Author

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
Copy link
Member

BYK commented Oct 21, 2022

@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
Copy link
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants