4 ms·

Seeing this my first thought was "Oh cool, so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs fo

Seeing this my first thought was "Oh cool, so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs for you." ... but it wasn't that (rather, just good arguments and suggestions). And now I'm wondering if my first thought is a thing? And if so, how it has worked out for users.

dereke 8y ago
Not quite a change log but something we've found useful with our clients is https://shippingreport.com https://shippingreport.com It uses PR messages to make a report of what changed. If your PR messages are nice (we use animated gifs to demo changes) then you end up with some really nice reports.
olivierlacan 8y ago
People have created million and a half tools to tackle this problem. Just look at the issues and you'll find a ton: https://github.com/olivierlacan/keep-a-changelog/issues?utf8=%E2%9C%93&q=is%3Aissue+tool https://github.com/olivierlacan/keep-a-changelog/issues?utf8... I've tried to refrain from endorsing tools because I feel like they risk making it easy to avoid doing what I actually encourage: curating the notable changes for a release with your mushy human brain for other mushy human brains. I know it's hard, but perhaps it's a good constraint. The idea that you will have the forethought of knowing when writing a commit that it'll be one of the notable entries in your future changelog seems a bit far-fetched to me. And as I tried to explain, the purpose of a commit is not the same as the purpose of a changelog entry, so there's definitely tension in the re-use of copy there. I get the instinct to automate everything. I'm just not sure this is something that should be automated. Now, an assistive tool to help maintainers review commits for missing notable changes within a changelog, that's something I could get behind.
- bendavis381 8y ago
  I think the issue with automation is it requires a cultural change for most companies / projects. People are very used to small atomic commits and so it’s hard to reduce the noise once parsed into a changelog. To make it work, you need each commit to be as meaningful as a line in the changelog. We use Phabricator and it’s default workflow, so have a clean linear git history. Phabricator already requires strict formatting for any new diff (title, description, testing, etc). It’s built into the culture of any org using Phab to consider commits as meaningful entries in the history of the project. So it would be very straightforward (technically and culturally) to require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for each commit and have yourself a automated and meaningful log.
  - anonytrary 8y ago
    > you need each commit to be as meaningful as a line in the changelog. Not really, your changelog-from-git-log generator doesn't need to incorporate every single commit. The vast majority of commits shouldn't be incorporated in a changelog anyway, since fine-grained commits serve a different purpose. It could incorporate, for example, version-change commits whose messages serve the exact same purpose as changelog entries. git commit -m "VERSION 1.1.0 <user readable desc of changes since 1.0.0>"
anonytrary 8y ago
That's sort of what I was talking about, but I was getting down-voted for not explaining myself. It seems redundant to keep a changelog with its own state when writing good, user-readable version-change commit messages is something you already do. Using git-rebase could help you work in a version-change specific commit meant for users. To clarify, not all of your commits need to be user-readable, since the majority of them are meant for developers -- just the sparse ones that capture the version change need to be user-readable. Then you'd have a full commit history for the nitty gritty details and a subset of your commits would be used to generate a pretty changelog.md for everyone who wants the TLDR.
aiooua 8y ago
> so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs for you https://github.com/aldrin/git-changelog https://github.com/aldrin/git-changelog https://asciinema.org/a/Jk8A5UEJGkhlalL4gl3HevC7e https://asciinema.org/a/Jk8A5UEJGkhlalL4gl3HevC7e

dereke 8y ago

Not quite a change log but something we've found useful with our clients is https://shippingreport.com https://shippingreport.com It uses PR messages to make a report of what changed. If your PR messages are nice (we use animated gifs to demo changes) then you end up with some really nice reports.

olivierlacan 8y ago

People have created million and a half tools to tackle this problem. Just look at the issues and you'll find a ton: https://github.com/olivierlacan/keep-a-changelog/issues?utf8=%E2%9C%93&q=is%3Aissue+tool https://github.com/olivierlacan/keep-a-changelog/issues?utf8... I've tried to refrain from endorsing tools because I feel like they risk making it easy to avoid doing what I actually encourage: curating the notable changes for a release with your mushy human brain for other mushy human brains. I know it's hard, but perhaps it's a good constraint. The idea that you will have the forethought of knowing when writing a commit that it'll be one of the notable entries in your future changelog seems a bit far-fetched to me. And as I tried to explain, the purpose of a commit is not the same as the purpose of a changelog entry, so there's definitely tension in the re-use of copy there. I get the instinct to automate everything. I'm just not sure this is something that should be automated. Now, an assistive tool to help maintainers review commits for missing notable changes within a changelog, that's something I could get behind.

bendavis381 8y ago
I think the issue with automation is it requires a cultural change for most companies / projects. People are very used to small atomic commits and so it’s hard to reduce the noise once parsed into a changelog. To make it work, you need each commit to be as meaningful as a line in the changelog. We use Phabricator and it’s default workflow, so have a clean linear git history. Phabricator already requires strict formatting for any new diff (title, description, testing, etc). It’s built into the culture of any org using Phab to consider commits as meaningful entries in the history of the project. So it would be very straightforward (technically and culturally) to require a simple title prefix ala Changelog (ADDED, FIXED, SECURITY, etc) for each commit and have yourself a automated and meaningful log.
- anonytrary 8y ago
  > you need each commit to be as meaningful as a line in the changelog. Not really, your changelog-from-git-log generator doesn't need to incorporate every single commit. The vast majority of commits shouldn't be incorporated in a changelog anyway, since fine-grained commits serve a different purpose. It could incorporate, for example, version-change commits whose messages serve the exact same purpose as changelog entries. git commit -m "VERSION 1.1.0 <user readable desc of changes since 1.0.0>"

anonytrary 8y ago

That's sort of what I was talking about, but I was getting down-voted for not explaining myself. It seems redundant to keep a changelog with its own state when writing good, user-readable version-change commit messages is something you already do. Using git-rebase could help you work in a version-change specific commit meant for users. To clarify, not all of your commits need to be user-readable, since the majority of them are meant for developers -- just the sparse ones that capture the version change need to be user-readable. Then you'd have a full commit history for the nitty gritty details and a subset of your commits would be used to generate a pretty changelog.md for everyone who wants the TLDR.

aiooua 8y ago

> so you format your git commit messages in a certain way, and then this tool will automatically generate changelogs for you https://github.com/aldrin/git-changelog https://github.com/aldrin/git-changelog https://asciinema.org/a/Jk8A5UEJGkhlalL4gl3HevC7e https://asciinema.org/a/Jk8A5UEJGkhlalL4gl3HevC7e