7 ms·

Keep a Changelog

223 points by soheilpro 5y ago

rp1 5y ago
Or you could just filter the commit history and use squash instead of merge.
- slaymaker1907 5y ago
  I still think a changelog may be useful. For example, if you are writing a library, a changelog should include a section for breaking changes. Ideally you should also be providing a migration guide, but a list of breaking changes should be done at a minimum. Git history is also not ideal for giving to users since the history is primarily intended for developers. If you actually want to use git history for this, I actually think non-squash merges are better since you can have the merge commit be very high level and use the other commits for technical details and incremental changes. However, even if you do regular merges, you absolutely still need to keep your history clean via rebasing before sending out a PR. Another tip for keeping your PRs clean without confusing people is to create a separate branch while working on feedback from the PR so you can still manipulate the history as needed while backing up your code to the remote server.
- gitgud 5y ago
  That's better than nothing, but code commits and changelogs have different use cases. Commit logs are for all changes, regardless of size or context. Whereas changelogs are for consumer-facing changes.
  - rp1 5y ago
    That's why you filter it...
petethepig 5y ago
Semantic pull requests [0] + conventional-changelog [1] + squashing PRs and you get almost the same results (and more) with great automation and self-documentation for the whole process: * 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 https://github.com/apps/semantic-pull-requests [1] - https://github.com/conventional-changelog/conventional-changelog https://github.com/conventional-changelog/conventional-chang... [2] - https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELOG.md https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELO...
- busbus 5y ago
  May I ask you why you want to squash every branch ? What is the size of the resulting commit (in terms of average modified files, lines of code) ?
  - majkinetor 5y ago
    One typical reason would be easier history following and eventually revert.
  - rezonant 5y ago
    I've shared this anecdote elsewhere but it's my go-to example. We recently had a new engineer join our team, we gave them a small piece of work related to a bigger feature we had completed months before they arrived. They tracked the feature back to the squashed PR commit, which of course referenced the Github PR URL- in there they had the engineer's summary and implementation caveats, the review comments from the rest of the team and the discussion context. They could reference all the commits made throughout the process from there. The PR itself used "Closes #X" syntax, so they could jump back to the engineering task and up into the product backlog item that spawned it. They nailed the change the first time :-) > 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
    - fphilipe 5y ago
      The merge commit also includes the link to the PR when merged via the GitHub UI (or locally via `hub merge $PR_URL`).
    - busbus 5y ago
      I understand the needs. But to me, I can’t see any real value to squashing other than cleaning local history before sharing the code. Also, and that’s important for me (maybe other people doesn’t care of it) I lose the ability to bisect more precisely. When I know that my guilty commit is a squashed one, I have to watch every modification to understand what went wrong, which takes time for me. 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).
rdpintqogeogsaa 5y ago
See also: The deb-changelog format[0]. [0] https://manpages.debian.org/testing/dpkg-dev/deb-changelog.5.en.html https://manpages.debian.org/testing/dpkg-dev/deb-changelog.5...
ChrisArchitect 5y ago
(2014) Anything new here?
- jayflux 5y ago
  I think the website updated
- ChrisArchitect 5y ago
  since this is a site about changelogs and version 1.0.0 entry says 2017. This is not new.
jayflux 5y ago
GitHub have developed a feature to generate release notes based off the commit history, might be worth trying. You can configure it to filter out users, group by labels etc https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes https://docs.github.com/en/repositories/releasing-projects-o... For those saying “just use commit history”, I once had to sift through 200 commits because the library author was too lazy to separate the breaking changes from the patches. It’s horrible for users of your library, a changelog doesn’t have to replicate your commit log but it should at the least be the “highlights” or need-to-know version of it.
- majkinetor 5y ago
  Gitlab has something like this since recently.
- rezonant 5y ago
  > For those saying “just use commit history”, I once had to sift through 200 commits Exactly... I think it's a good idea to "roll up" the impact of the changes so that users and external developers can easily understand what was changed without getting too "in the weeds"- raw commit messages are generally the opposite of that. > GitHub have developed a feature to generate release notes The annoying part here is that if you are using a branch-based CI auto-deployment (without an "Approve" step) then you have to push the branch before writing the release notes. Anyway I just do `git cherry -v release` or so from `main` (for instance) and paste the results into the Release Notes at the bottom and put my summaries at the top. The benefit of just pasting the results is that Github will detect the commit IDs and link to them automatically. It makes for a pretty good experience where you can sum it up and have the full commit messages for those interested.
fiatjaf 5y ago
Changelogs without reference to the actual source changes are completely and utterly useless. Changelogs with reference to the actual source changes are support natively by git. They're called commits.
ChrisMarshallNY 5y ago
I've been hand-writing a CHANGELOG.md file, in each of my repos, for a long time. Before that, I used to keep it as a section of my README.md file. I got used to the second file, after using CocoaPods. I don't really use CocoaPods anymore, but they would render the CHANGELOG.md file in a separate tab, which was nice. I don't think anyone else does that. I think a hand-written changelog is better than a semantically-generated one, because it connects the developers' mindset to the consumer (usually, another developer). It says "These are the aspects of this release that I think are important." A semantically-written changelog doesn't actually need to be kept. It can be auto-generated on demand. As long as the developer keeps good commit notes, with things like issue numbers, then this could be useful.
- ChrisMarshallNY 5y ago
  FYI. Here’s a very long CHANGELOG (over ten years): https://github.com/bmlt-enabled/bmlt-root-server/blob/master/CHANGELOG.md https://github.com/bmlt-enabled/bmlt-root-server/blob/master... It was in the README for most of that time. It has just been broken out into a separate file, by the new team.
wagoodman 5y ago
The approach I like to take is to curate issues and PR with semantic titles and organize them by label ("bug", "enhancement", etc) or linking PRs to an already curated issue. This way automation can use these to generate the changlog for me on each release based on closed issues and unlinked PRs since the last release. We wrote Chronicle to do that automation for us: https://github.com/anchore/chronicle https://github.com/anchore/chronicle . The nice thing about this... since you typically curate issues during the development process anyway, if you're doing that right then you get a nice looking changlog for free! We use this approach with our core tools, Syft and Grype (some changlog examples: https://github.com/anchore/syft/releases/tag/v0.31.0 https://github.com/anchore/syft/releases/tag/v0.31.0 and https://github.com/anchore/grype/releases/tag/v0.26.1 https://github.com/anchore/grype/releases/tag/v0.26.1 ). Always happy to hear new feature ideas and possible customizations for Chronicle (put in an issue and let's chat )!
yardstick 5y ago
Re “ Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day.” I disagree. ISO 8601 is great for machine readable dates. For human readable dates I prefer to spell the month out. 17 July 2017 is more readable than 2020-07-17. Yes it is in English but if your audience is in English and the rest of your content is in English then it’s fine.
- d1sxeyes 5y ago
  DD-MMM-YYYY is also very readable.
- avel 5y ago
  17 July 2017 removed ambiguity but still feels a bit awkward for US people.
- dspillett 5y ago
  That is a UI issue though. Internally keep dates and times as proper date/time typed, when you have to use strings use ISO 8601 as it is unambiguous (aside from an ancient bug in MS SQL Server if you happen to have your user locale set to British), only bother converting to some other format for display purposes. For a changelog in text format I think it is safe to assume the reader will understand yyyy-mm-dd, and it is safer than dd/mm/yyyy or mm/dd/yyyy due to the lack of ambiguity. Also if they don't understand they'll know and hopefully learn the standard, where with other numeric formats they could blindly assume they have understood. > 17 July 2017 is more readable than 2020-07-17 I don't agree there, but that could be what I'm used to. The textual month at least removes the ambiguity so is significantly preferable to the same order in a numeric-only form. > Yes it is in English but if your audience is in English… But if a chunk of your audience is American? IIRC they generally verbalise dates in mdy order which is why they ended up using that order in numeric forms, so they may find it as jarring, or more so, as ymd. Not that I alter my spelling for American comfort, but as clarity-to-the-audience is the arguement here… If course if the text you are working on is mainly for your benefit, forget everyone else and do what works best for your style/comprehension/preference.
maximedupre 5y ago
That's cool, but I was hoping for a tool that generates a nifty little text file like that. It might be a cool idea to automate the process.
jandrusk 5y ago
Does that mean you need a changelog for each changelog, since each changelog will be part of the project?
johnisgood 5y ago
Wait, what about `git merge --log`? It gives you a list of commits instead, which reads the same as a Changelog would, provided that the commit messages are not akin to messages like "stuff...".
jamesmishra 5y ago
Commit messages often aren't nontechnical enough to make for an accessible changelog. I would like to encourage developers to maintain changelog for their projects, but to host the changelogs outside of the project's Git repository. Maybe put it on the "Wiki" or "Releases" pages on GitHub. When the changelog is an actual file in the Git repository, it becomes another source for merge and rebase conflicts.
bromuro 5y ago
> Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc. I’d rather fix that. I’ve been following the suggestion from this website in the past. It is a nice take but tedious and boring. Better have commit messages. For example: https://www.conventionalcommits.org https://www.conventionalcommits.org
- nirvdrum 5y ago
  I come across way too many commit messages that exist solely to drive some sort of connected tool (CI, CD, issue tracker, etc.) or have some arbitrary character cut-off, so the messages are borderline cryptic. Add the typical back-and-forth on design in repos and you end up with entries that don't correspond to what's shipped in the release. The reverse chronological order of messages doesn't help much either. And a surprisingly large number of projects don't tag their releases, so picking where to start reading from is an exercise in frustration. I find a changelog is a great place to provide a high level summary of changes and a good opportunity to highlight backwards-incompatible changes or API changes users should be aware of. If your commit messages are of the form "Fix #123" (without the issue title), it's also a good place to summarize #123 so your users don't have to cross-check everything with GitHub. I'd love to see a commit log that was consumer-friendly. But, as long as devs are writing messages within the constraints of other tools, I don't see it happening. Conventional commits is an interesting idea, but for those keeping messages to 72 characters, it eats up a fair bit of the message. Also, a lot of it ends up being noise that you wouldn't want in a user-facing changelog (e.g., "test:" and "refactor:").
- jopsen 5y ago
  I think I've often seen a feature land, followed by 2-3 small PRs fixing corner cases discovered during dev-release testing. Or you agree to land a PR with some aspects left to be fixed in follow up PRs. Typically, when projects are non-trivial in size, providing a changelog summarizing the important changes is useful.
  - rezonant 5y ago
    Great point. So if you want that to come out atomically and "clean" you need to rebase the world- nontrival at best. I think that's worse than having multiple PRs around a feature. But I guess real engineers get it right the first time /s
deleted 5y ago
[deleted]
dang 5y ago
Past related threads: Keep a Changelog - https://news.ycombinator.com/item?id=22295555 https://news.ycombinator.com/item?id=22295555 - Feb 2020 (1 comment) Keep a Changelog - https://news.ycombinator.com/item?id=17631326 https://news.ycombinator.com/item?id=17631326 - July 2018 (71 comments) Keep a Changelog - https://news.ycombinator.com/item?id=12370119 https://news.ycombinator.com/item?id=12370119 - Aug 2016 (45 comments) Keep a Changelog - https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627 - Feb 2015 (43 comments)

Keep a Changelog

223 points by soheilpro 5y ago

rp1 5y ago

Or you could just filter the commit history and use squash instead of merge.

slaymaker1907 5y ago
I still think a changelog may be useful. For example, if you are writing a library, a changelog should include a section for breaking changes. Ideally you should also be providing a migration guide, but a list of breaking changes should be done at a minimum. Git history is also not ideal for giving to users since the history is primarily intended for developers. If you actually want to use git history for this, I actually think non-squash merges are better since you can have the merge commit be very high level and use the other commits for technical details and incremental changes. However, even if you do regular merges, you absolutely still need to keep your history clean via rebasing before sending out a PR. Another tip for keeping your PRs clean without confusing people is to create a separate branch while working on feedback from the PR so you can still manipulate the history as needed while backing up your code to the remote server.
gitgud 5y ago
That's better than nothing, but code commits and changelogs have different use cases. Commit logs are for all changes, regardless of size or context. Whereas changelogs are for consumer-facing changes.
- rp1 5y ago
  That's why you filter it...

petethepig 5y ago

Semantic pull requests [0] + conventional-changelog [1] + squashing PRs and you get almost the same results (and more) with great automation and self-documentation for the whole process: * 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 https://github.com/apps/semantic-pull-requests [1] - https://github.com/conventional-changelog/conventional-changelog https://github.com/conventional-changelog/conventional-chang... [2] - https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELOG.md https://github.com/pyroscope-io/pyroscope/blob/main/CHANGELO...

busbus 5y ago
May I ask you why you want to squash every branch ? What is the size of the resulting commit (in terms of average modified files, lines of code) ?
- majkinetor 5y ago
  One typical reason would be easier history following and eventually revert.
- rezonant 5y ago
  I've shared this anecdote elsewhere but it's my go-to example. We recently had a new engineer join our team, we gave them a small piece of work related to a bigger feature we had completed months before they arrived. They tracked the feature back to the squashed PR commit, which of course referenced the Github PR URL- in there they had the engineer's summary and implementation caveats, the review comments from the rest of the team and the discussion context. They could reference all the commits made throughout the process from there. The PR itself used "Closes #X" syntax, so they could jump back to the engineering task and up into the product backlog item that spawned it. They nailed the change the first time :-) > 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
  - fphilipe 5y ago
    The merge commit also includes the link to the PR when merged via the GitHub UI (or locally via `hub merge $PR_URL`).
  - busbus 5y ago
    I understand the needs. But to me, I can’t see any real value to squashing other than cleaning local history before sharing the code. Also, and that’s important for me (maybe other people doesn’t care of it) I lose the ability to bisect more precisely. When I know that my guilty commit is a squashed one, I have to watch every modification to understand what went wrong, which takes time for me. 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).

rdpintqogeogsaa 5y ago

See also: The deb-changelog format[0]. [0] https://manpages.debian.org/testing/dpkg-dev/deb-changelog.5.en.html https://manpages.debian.org/testing/dpkg-dev/deb-changelog.5...

ChrisArchitect 5y ago

(2014) Anything new here?

jayflux 5y ago
I think the website updated
ChrisArchitect 5y ago
since this is a site about changelogs and version 1.0.0 entry says 2017. This is not new.

jayflux 5y ago

GitHub have developed a feature to generate release notes based off the commit history, might be worth trying. You can configure it to filter out users, group by labels etc https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes https://docs.github.com/en/repositories/releasing-projects-o... For those saying “just use commit history”, I once had to sift through 200 commits because the library author was too lazy to separate the breaking changes from the patches. It’s horrible for users of your library, a changelog doesn’t have to replicate your commit log but it should at the least be the “highlights” or need-to-know version of it.

majkinetor 5y ago
Gitlab has something like this since recently.
rezonant 5y ago
> For those saying “just use commit history”, I once had to sift through 200 commits Exactly... I think it's a good idea to "roll up" the impact of the changes so that users and external developers can easily understand what was changed without getting too "in the weeds"- raw commit messages are generally the opposite of that. > GitHub have developed a feature to generate release notes The annoying part here is that if you are using a branch-based CI auto-deployment (without an "Approve" step) then you have to push the branch before writing the release notes. Anyway I just do `git cherry -v release` or so from `main` (for instance) and paste the results into the Release Notes at the bottom and put my summaries at the top. The benefit of just pasting the results is that Github will detect the commit IDs and link to them automatically. It makes for a pretty good experience where you can sum it up and have the full commit messages for those interested.

fiatjaf 5y ago

Changelogs without reference to the actual source changes are completely and utterly useless. Changelogs with reference to the actual source changes are support natively by git. They're called commits.

ChrisMarshallNY 5y ago

I've been hand-writing a CHANGELOG.md file, in each of my repos, for a long time. Before that, I used to keep it as a section of my README.md file. I got used to the second file, after using CocoaPods. I don't really use CocoaPods anymore, but they would render the CHANGELOG.md file in a separate tab, which was nice. I don't think anyone else does that. I think a hand-written changelog is better than a semantically-generated one, because it connects the developers' mindset to the consumer (usually, another developer). It says "These are the aspects of this release that I think are important." A semantically-written changelog doesn't actually need to be kept. It can be auto-generated on demand. As long as the developer keeps good commit notes, with things like issue numbers, then this could be useful.

ChrisMarshallNY 5y ago
FYI. Here’s a very long CHANGELOG (over ten years): https://github.com/bmlt-enabled/bmlt-root-server/blob/master/CHANGELOG.md https://github.com/bmlt-enabled/bmlt-root-server/blob/master... It was in the README for most of that time. It has just been broken out into a separate file, by the new team.

wagoodman 5y ago

The approach I like to take is to curate issues and PR with semantic titles and organize them by label ("bug", "enhancement", etc) or linking PRs to an already curated issue. This way automation can use these to generate the changlog for me on each release based on closed issues and unlinked PRs since the last release. We wrote Chronicle to do that automation for us: https://github.com/anchore/chronicle https://github.com/anchore/chronicle . The nice thing about this... since you typically curate issues during the development process anyway, if you're doing that right then you get a nice looking changlog for free! We use this approach with our core tools, Syft and Grype (some changlog examples: https://github.com/anchore/syft/releases/tag/v0.31.0 https://github.com/anchore/syft/releases/tag/v0.31.0 and https://github.com/anchore/grype/releases/tag/v0.26.1 https://github.com/anchore/grype/releases/tag/v0.26.1 ). Always happy to hear new feature ideas and possible customizations for Chronicle (put in an issue and let's chat )!

yardstick 5y ago

Re “ Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day.” I disagree. ISO 8601 is great for machine readable dates. For human readable dates I prefer to spell the month out. 17 July 2017 is more readable than 2020-07-17. Yes it is in English but if your audience is in English and the rest of your content is in English then it’s fine.

d1sxeyes 5y ago
DD-MMM-YYYY is also very readable.
avel 5y ago
17 July 2017 removed ambiguity but still feels a bit awkward for US people.
dspillett 5y ago
That is a UI issue though. Internally keep dates and times as proper date/time typed, when you have to use strings use ISO 8601 as it is unambiguous (aside from an ancient bug in MS SQL Server if you happen to have your user locale set to British), only bother converting to some other format for display purposes. For a changelog in text format I think it is safe to assume the reader will understand yyyy-mm-dd, and it is safer than dd/mm/yyyy or mm/dd/yyyy due to the lack of ambiguity. Also if they don't understand they'll know and hopefully learn the standard, where with other numeric formats they could blindly assume they have understood. > 17 July 2017 is more readable than 2020-07-17 I don't agree there, but that could be what I'm used to. The textual month at least removes the ambiguity so is significantly preferable to the same order in a numeric-only form. > Yes it is in English but if your audience is in English… But if a chunk of your audience is American? IIRC they generally verbalise dates in mdy order which is why they ended up using that order in numeric forms, so they may find it as jarring, or more so, as ymd. Not that I alter my spelling for American comfort, but as clarity-to-the-audience is the arguement here… If course if the text you are working on is mainly for your benefit, forget everyone else and do what works best for your style/comprehension/preference.

maximedupre 5y ago

That's cool, but I was hoping for a tool that generates a nifty little text file like that. It might be a cool idea to automate the process.

jandrusk 5y ago

Does that mean you need a changelog for each changelog, since each changelog will be part of the project?

johnisgood 5y ago

Wait, what about `git merge --log`? It gives you a list of commits instead, which reads the same as a Changelog would, provided that the commit messages are not akin to messages like "stuff...".

jamesmishra 5y ago

Commit messages often aren't nontechnical enough to make for an accessible changelog. I would like to encourage developers to maintain changelog for their projects, but to host the changelogs outside of the project's Git repository. Maybe put it on the "Wiki" or "Releases" pages on GitHub. When the changelog is an actual file in the Git repository, it becomes another source for merge and rebase conflicts.

bromuro 5y ago

> Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc. I’d rather fix that. I’ve been following the suggestion from this website in the past. It is a nice take but tedious and boring. Better have commit messages. For example: https://www.conventionalcommits.org https://www.conventionalcommits.org

nirvdrum 5y ago
I come across way too many commit messages that exist solely to drive some sort of connected tool (CI, CD, issue tracker, etc.) or have some arbitrary character cut-off, so the messages are borderline cryptic. Add the typical back-and-forth on design in repos and you end up with entries that don't correspond to what's shipped in the release. The reverse chronological order of messages doesn't help much either. And a surprisingly large number of projects don't tag their releases, so picking where to start reading from is an exercise in frustration. I find a changelog is a great place to provide a high level summary of changes and a good opportunity to highlight backwards-incompatible changes or API changes users should be aware of. If your commit messages are of the form "Fix #123" (without the issue title), it's also a good place to summarize #123 so your users don't have to cross-check everything with GitHub. I'd love to see a commit log that was consumer-friendly. But, as long as devs are writing messages within the constraints of other tools, I don't see it happening. Conventional commits is an interesting idea, but for those keeping messages to 72 characters, it eats up a fair bit of the message. Also, a lot of it ends up being noise that you wouldn't want in a user-facing changelog (e.g., "test:" and "refactor:").
jopsen 5y ago
I think I've often seen a feature land, followed by 2-3 small PRs fixing corner cases discovered during dev-release testing. Or you agree to land a PR with some aspects left to be fixed in follow up PRs. Typically, when projects are non-trivial in size, providing a changelog summarizing the important changes is useful.
- rezonant 5y ago
  Great point. So if you want that to come out atomically and "clean" you need to rebase the world- nontrival at best. I think that's worse than having multiple PRs around a feature. But I guess real engineers get it right the first time /s

deleted 5y ago

[deleted]

dang 5y ago

Past related threads: Keep a Changelog - https://news.ycombinator.com/item?id=22295555 https://news.ycombinator.com/item?id=22295555 - Feb 2020 (1 comment) Keep a Changelog - https://news.ycombinator.com/item?id=17631326 https://news.ycombinator.com/item?id=17631326 - July 2018 (71 comments) Keep a Changelog - https://news.ycombinator.com/item?id=12370119 https://news.ycombinator.com/item?id=12370119 - Aug 2016 (45 comments) Keep a Changelog - https://news.ycombinator.com/item?id=9054627 https://news.ycombinator.com/item?id=9054627 - Feb 2015 (43 comments)