In general, as a developer-consumer of them, I have found automatically-generated-from-commits changelogs to be not so useful, but I don't know if I've experienced any using the conventions you are recommending (which I dont' understand!).
In the small projects I write, I include links to the PR in the manually created CHANGELOG (the delta of which is part of the PR) simply by making the PR, then making another commit/ammend in the PR to add it's own url to the CHANGELOG. These are some extra steps, it's true.
It forces you to think a moment for a good PR title, but it is an small price to pay when it gives you a 0 extra work changelog that is good enough for semi-internal use.
git --no-pager log | grep 'CHANGELOG: '
https://git-scm.com/book/en/v2/Customizing-Git-An-Example-Gi...> Ugh. One of my pet peeves is the generation of release notes from commit messages. Commit messages and PR descriptions have a different audience (i.e. contributors) from release notes (i.e. users).
> For example, take a look at ESLint's autogenerated changelog [1]:
67c0074 Update: Suggest missing rule in flat config (fixes #14027) (#15074) (Nicholas C. Zakas)
cf34e5c Update: space-before-blocks ignore after switch colons (fixes #15082) (#15093) (Milos Djermanovic)
c9efb5f Fix: preserve formatting when rules are removed from disable directives (#15081) (Milos Djermanovic)
14a4739 Update: no-new-func rule catching eval case of MemberExpression (#14860) (Mojtaba Samimi)
7f2346b Docs: Update release blog post template (#15094) (Nicholas C. Zakas)
fabdf8a Chore: Remove target.all from Makefile.js (#15088) (Hirotaka Tagawa / wafuwafu13)
e3cd141 Sponsors: Sync README with website (ESLint Jenkins)
05d7140 Chore: document target global in Makefile.js (#15084) (Hirotaka Tagawa / wafuwafu13)
0a1a850 Update: include ruleId in error logs (fixes #15037) (#15053) (Ari Perkkiö)
47be800 Chore: test Property > .key with { a = 1 } pattern (fixes #14799) (#15072) (Milos Djermanovic)
a744dfa Docs: Update CLA info (#15058) (Brian Warner)
9fb0f70 Chore: fix bug report template (#15061) (Milos Djermanovic)
f87e199 Chore: Cleanup issue templates (#15039) (Nicholas C. Zakas)
> I'm reading release notes to get a feel for how the new release might impact me. This takes so much time to scan, because there's so much useless cruft (to me, as a user) I have to ignore.> What's worked very well for me is to simply have an "I updated the changelog, if applicable" entry in my PR template checklist. Then when I cut a new release, I simply add the release date above the release notes currently listed under "Unreleased", and they'll list all relevant changes, reviewed during the pull request to verify that it is relevant to users.
> [1] https://github.com/eslint/eslint/blob/master/CHANGELOG.md
But it is a _way_ better starting point to write a changelog that 'usual' commit messages or PR descriptions.
I use custom scheme tho, using Gitlab issue title and issue labels. I find this more meaningful since one issue can contain multiple PRs and I still want single changelog line.
We do this and it works great, but I've still found value in summarizing things in a digest (ie changelog or release notes, depending on the context)
What is the size of the resulting commit (in terms of average modified files, lines of code) ?
> What is the size of the resulting commit (in terms of average modified files, lines of code) ?
Lately I'm starting to advocate squashing PR branches even if they have only a single commit. The real benefit here is that Github puts the PR URL into the squashed commit message. It automates the "context links" regardless of whether a PR branch ends up being 1 commit or 50
Also, everything you describe can be achieved with a merge commit. As a side effect, when you look at the history, you may be annoyed with small commits that may not interest you. But Git can help by displaying only merge commit (with --first-parent option).
True that you can achieve it in a merge commit. And I think Github includes the PR URL in a merge commit as well iirc. I suppose my main argument is really just that the always-rebase strategy that was trendy for awhile has some downsides over squash/merge commit /shrug
> The real benefit here is that Github puts the PR URL into the squashed commit message.
While not in the commit message, github will show you the PR a commit is part of in it's commit view regardless, also for every commit in a PR whether it's one commit or 50. Which I do find invaluable for tracing the documentation of a change, agreed! Not everyone knows about this feature (I don't think it's been there forever) in github UI.
Eg notice the `#279` included in this github commit UI display (the PR was, I'm pretty sure, not "squashed").
https://github.com/traject/traject/commit/10339e774e92e57f44...
We use release-please to automatically generate WIP "release PRs" so we can see the exact changelog (for a candidate release) drafted as merges come in.
I also recognize that for full-speed delivery, they are suboptimal in that they sit directly on the critical path. After reviewing the code of the PR, there is now an extra context switch to also review the title/semantics.
So the complexity of turning a list of PRs into a changelog does not disapper, it gets hidden within each individual PR.
* you'll never forget to add something to changelog
* you get links to PRs in your changelog
* it's much faster to make edits to PR messages compared to editing files
* outside contributors get familiarized with the practice much faster (imagine getting new contributors to update changelogs)
We recently adopted this practice at Pyroscope and it's been working out pretty well for us [2], I can certainly recommend it.
[0] - https://github.com/apps/semantic-pull-requests
[1] - https://github.com/conventional-changelog/conventional-chang...
[2] - https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELO...