6 ms·

Generate Your Changelog From GitHub Issues

88 points by skywinder 12y ago

zimbatm 12y ago
Might be better than what I'm currently using. The `git changelog` command from the git-extras package is also quite useful. It just takes the git log messages from the git history until the last tag and updates the `{History,Changelog}.md`. https://github.com/tj/git-extras/blob/master/bin/git-changelog https://github.com/tj/git-extras/blob/master/bin/git-changel...
scrapcode 12y ago
I really appreciate the attention to detail in every little thing including the README. Very inspiring. This is a serious question for HN: Is it considered rude to make pull requests to fix grammar? The English is great, but is made more apparent in some locations (such as headers in the README) that it is a second language, but the first thing I thought to myself was "that'd be rude".
- impostervt 12y ago
  Just my opinion, but I don't think it would be rude. Even thought I KNOW it's not really relevant, I've caught myself trusting some projects less if the Readme isn't well written.
- omahlama 12y ago
  That sort of thing happens all the time on stackoverflow, where most of the users aren't native English speakers. Go for it!
- akerl_ 12y ago
  In my experience, one of the upsides of GitHub and similar services is that they drastically lower the process headache of merging patches. When merging a patch means getting it out of the email and applying it to your branch, confirming it's valid / what changed, running your tests, then merging and pushing up the new version, it's quick to see why single-character or grammar/spelling fixes can be a burden. With GitHub, I can see the PR, the diff, whether it'll merge cleanly, and whether my TravisCI tests pass right from the PR's page, and all I need to do is hit the Merge button. It makes me much more likely to review/merge PRs.
- xomateix 12y ago
  As a non native english speaker I would really appreciate any correction.
- skywinder 12y ago
  Yep. I know, my english is not well. So, I will much apreciate a PR with grammar fixes.
  - scrapcode 12y ago
    Your English is just fine. Excellent, even, for being a second language.
  - duaneb 12y ago
    In this case, you'd want 'good' instead of 'well'—your english is good and you speak english well.
    - skywinder 12y ago
      Good to know! :) Thanks!
- evantahler 12y ago
  I'm a native english speaker who just happens to be a terrible speller. I consider it a measure of project success when someone who isn't a native english speaker corrects me :D
- tych0 12y ago
  No, it's not rude. For me personally, I just think it's great that someone else was interested in the code. I would venture a guess that 95% of the ESL speakers I know just want to get better, and would love to be corrected.
- kmfrk 12y ago
  It's not rude; it just ideally needs its own section or priority setting so they don't appear on par with bug fixes and the like.
- tessierashpool 12y ago
  I do it all the time, most people seem to like it. I usually apologize for being "that guy," though, because I don't want anyone taking it personally.
rlpb 12y ago
I don't understand why a changelog is necessary nowadays. Surely all the benefits that the author addresses here could be dynamic features of Github, Gitlab, etc? He does answer the FAQ "I already use GitHub Releases. Why do I need this?" but his answer doesn't really address the point that this comes down to missing functionality in such tooling and should be fixed there, rather than in a static file generator.
- mercurial 12y ago
  > I don't understand why a changelog is necessary nowadays. Surely all the benefits that the author addresses here could be dynamic features of Github, Gitlab, etc? Personally, I wouldn't want to go to Github every time I download a new version of a library. Text files are fine.
- skywinder 12y ago
  I also want to make close integration with GitHub Releases. Here is an issue with details: https://github.com/skywinder/github-changelog-generator/issues/56 https://github.com/skywinder/github-changelog-generator/issu...
- hobarrera 12y ago
  Personally, I'm not a big fan of GitHub releases. They're not really part of my code, or my repo. They're some metadata locked inside github that doesn't carry along with the project. A CHANGELOG.md is part of your repo/project. You can change where you host your git repos (eg: gitlab), and carry that over. Disclaimer: I don't use changelogs either. I can't be bothered with them. Users technical enough to want to know what's been changed in such fine grained detail can use `git log --oneline`.
- tenfingers 12y ago
  A generated changelog and/or a list of changes straight out of source control is not a substitute for a good release notes files. In fact, while I used to do the same in the past (back to cvsps!), I now just use the log as a template for what I'm going to write, to remember what I did. As an user I'm not interested in source details, minor cosmetic fixes and internals. I want to know what's new compared to the last release, what are the user facing changes, and any upgrade issues I might be facing. These are usually expressed just in a few paragraphs in a very discursive fashion. I personally hate straight-form-source changelogs. I do not read them as an user (too verbose), I don't use them as a developer (I use the scm directly!). There's a tendency for developers using git to conflate the two, since history can be rewritten. I think it's a major mistake. Commit logs are meant to aid developers. Commit logs will inevitably contain redundant information about the same logical change, even when you try hard to hide it. This is all useless information for users. On the contrary, dumbing down the history just for the sake of readability will also hurt the developers in the long run.
tonyhb 12y ago
It would work well if your issues are all correctly formatted (ie "Fix: XYZ", "Add: XYZ"). For open source projects, though, you'd have a ton of "Closed Issue" items for random questions where people treat issues as forums. That puts me off.
- xomateix 12y ago
  Maybe you could label the issues that have been closed because they were just questions and then use the following option to exclude those issues: --exclude-labels x,y,z
- skywinder 12y ago
  Hey, thats for a labels! As I mention in README: any issue, that has label "question duplicate invalid wontfix" will be excluded by default. And you can change list of this labels.
  - tonyhb 12y ago
    Awesome! I totally didn't see that. My own fault for skimming!
evantahler 12y ago
Question/Poll: Do you prefer `changelog.md` or the releases tool built into github (IE: https://github.com/evantahler/actionhero/releases https://github.com/evantahler/actionhero/releases).
- hobarrera 12y ago
  My reply below [1] talks about the pitfalls of the releaes too a bit. There's several other comments surrounding it already. That said, I feel that changelogs are way better, being more flexible and more in control of the user. I do feel that a lot of people can't keep one that well though. We don't need fine-grained details of every internal code refactor on a major-release changelog, since it's only relevant to devs (and they'll usually see the commit logs anyway). [1]: https://news.ycombinator.com/item?id=9237398 https://news.ycombinator.com/item?id=9237398
  - skywinder 12y ago
    > We don't need fine-grained details of every internal code refactor - Thats why you shouldn't dump commit messages to logs! > since it's only relevant to devs Since you are hosting your project on GitHub - you are expecting, that it not only for end-users, and for Developers also, huh? So, why not to maintain neat change log for them? (And use GitHub Releases for end-users change log, without "fine-grained details of every internal code refactor")
- insin 12y ago
  Both: keeping a changelog and copying a section to the latest relase after tagging it, since they're both Markdown.
  - skywinder 12y ago
    Yep. I would like to implement it also: https://github.com/skywinder/github-changelog-generator/issues/56 https://github.com/skywinder/github-changelog-generator/issu...
farslan 12y ago
This is very nice. I was creating manual changelog via Github releases. I really like that way because I can see the latest changes immediately and pick the relevant changes: https://github.com/fatih/vim-go/releases https://github.com/fatih/vim-go/releases
jonperl 12y ago
Very cool. We have been building a slack bot to do something similar, for internal release notes https://github.com/DispatchMe/meteor-rosie https://github.com/DispatchMe/meteor-rosie
mikegerwitz 12y ago
For those looking to generate changelogs, but not from issues or something GitHub-specific, gnulib has a tool to generate changelogs from commit messages: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=build-aux/gitlog-to-changelog http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=bu...
- skywinder 12y ago
  >Dumping a diff of commit logs. Just don’t do that, you’re helping nobody. (c)https://github.com/olivierlacan/keep-a-changelog https://github.com/olivierlacan/keep-a-changelog It's very hard to maintain it in a good maner. The Issues fits for this purpose much better. (JMHO)
RandomBK 12y ago
I see this being very useful for generating a rough draft for the changelog that you can then edit and elaborate on. I find that not all commits change public facing APIs, so it would still be necessary go go over it and remove internal changes.
alfonsodev 12y ago
In the projects I work we prefix every commit with codename and 3 digits, I extract the change log from this command: git log v0.3...v0.4 --oneline | grep -oh -B 1 "CODENAME-[0-9][0-9][0-9]" | sort | uniq
- skywinder 12y ago
  I will add this feature in the future to this script also! https://github.com/skywinder/github-changelog-generator/issues/51 https://github.com/skywinder/github-changelog-generator/issu...
hiroshi3110 12y ago
I have used similar tool called `git-pr-release` which create release PR from bunch of topic PRs. I added a function that create a Github release from release PRs. https://github.com/hiroshi/git-pr-release/tree/create_release#the---release-flag https://github.com/hiroshi/git-pr-release/tree/create_releas...

88 points by skywinder 12y ago

Might be better than what I'm currently using. The `git changelog` command from the git-extras package is also quite useful. It just takes the git log messages from the git history until the last tag and updates the `{History,Changelog}.md`. https://github.com/tj/git-extras/blob/master/bin/git-changelog https://github.com/tj/git-extras/blob/master/bin/git-changel...

scrapcode 12y ago

I really appreciate the attention to detail in every little thing including the README. Very inspiring. This is a serious question for HN: Is it considered rude to make pull requests to fix grammar? The English is great, but is made more apparent in some locations (such as headers in the README) that it is a second language, but the first thing I thought to myself was "that'd be rude".

impostervt 12y ago
Just my opinion, but I don't think it would be rude. Even thought I KNOW it's not really relevant, I've caught myself trusting some projects less if the Readme isn't well written.
omahlama 12y ago
That sort of thing happens all the time on stackoverflow, where most of the users aren't native English speakers. Go for it!
akerl_ 12y ago
In my experience, one of the upsides of GitHub and similar services is that they drastically lower the process headache of merging patches. When merging a patch means getting it out of the email and applying it to your branch, confirming it's valid / what changed, running your tests, then merging and pushing up the new version, it's quick to see why single-character or grammar/spelling fixes can be a burden. With GitHub, I can see the PR, the diff, whether it'll merge cleanly, and whether my TravisCI tests pass right from the PR's page, and all I need to do is hit the Merge button. It makes me much more likely to review/merge PRs.
xomateix 12y ago
As a non native english speaker I would really appreciate any correction.
skywinder 12y ago
Yep. I know, my english is not well. So, I will much apreciate a PR with grammar fixes.
- scrapcode 12y ago
  Your English is just fine. Excellent, even, for being a second language.
- duaneb 12y ago
  In this case, you'd want 'good' instead of 'well'—your english is good and you speak english well.
  - skywinder 12y ago
    Good to know! :) Thanks!
evantahler 12y ago
I'm a native english speaker who just happens to be a terrible speller. I consider it a measure of project success when someone who isn't a native english speaker corrects me :D
tych0 12y ago
No, it's not rude. For me personally, I just think it's great that someone else was interested in the code. I would venture a guess that 95% of the ESL speakers I know just want to get better, and would love to be corrected.
kmfrk 12y ago
It's not rude; it just ideally needs its own section or priority setting so they don't appear on par with bug fixes and the like.
tessierashpool 12y ago
I do it all the time, most people seem to like it. I usually apologize for being "that guy," though, because I don't want anyone taking it personally.

rlpb 12y ago

I don't understand why a changelog is necessary nowadays. Surely all the benefits that the author addresses here could be dynamic features of Github, Gitlab, etc? He does answer the FAQ "I already use GitHub Releases. Why do I need this?" but his answer doesn't really address the point that this comes down to missing functionality in such tooling and should be fixed there, rather than in a static file generator.

mercurial 12y ago
> I don't understand why a changelog is necessary nowadays. Surely all the benefits that the author addresses here could be dynamic features of Github, Gitlab, etc? Personally, I wouldn't want to go to Github every time I download a new version of a library. Text files are fine.
skywinder 12y ago
I also want to make close integration with GitHub Releases. Here is an issue with details: https://github.com/skywinder/github-changelog-generator/issues/56 https://github.com/skywinder/github-changelog-generator/issu...
hobarrera 12y ago
Personally, I'm not a big fan of GitHub releases. They're not really part of my code, or my repo. They're some metadata locked inside github that doesn't carry along with the project. A CHANGELOG.md is part of your repo/project. You can change where you host your git repos (eg: gitlab), and carry that over. Disclaimer: I don't use changelogs either. I can't be bothered with them. Users technical enough to want to know what's been changed in such fine grained detail can use `git log --oneline`.
tenfingers 12y ago
A generated changelog and/or a list of changes straight out of source control is not a substitute for a good release notes files. In fact, while I used to do the same in the past (back to cvsps!), I now just use the log as a template for what I'm going to write, to remember what I did. As an user I'm not interested in source details, minor cosmetic fixes and internals. I want to know what's new compared to the last release, what are the user facing changes, and any upgrade issues I might be facing. These are usually expressed just in a few paragraphs in a very discursive fashion. I personally hate straight-form-source changelogs. I do not read them as an user (too verbose), I don't use them as a developer (I use the scm directly!). There's a tendency for developers using git to conflate the two, since history can be rewritten. I think it's a major mistake. Commit logs are meant to aid developers. Commit logs will inevitably contain redundant information about the same logical change, even when you try hard to hide it. This is all useless information for users. On the contrary, dumbing down the history just for the sake of readability will also hurt the developers in the long run.

tonyhb 12y ago

It would work well if your issues are all correctly formatted (ie "Fix: XYZ", "Add: XYZ"). For open source projects, though, you'd have a ton of "Closed Issue" items for random questions where people treat issues as forums. That puts me off.

xomateix 12y ago
Maybe you could label the issues that have been closed because they were just questions and then use the following option to exclude those issues: --exclude-labels x,y,z
skywinder 12y ago
Hey, thats for a labels! As I mention in README: any issue, that has label "question duplicate invalid wontfix" will be excluded by default. And you can change list of this labels.
- tonyhb 12y ago
  Awesome! I totally didn't see that. My own fault for skimming!

evantahler 12y ago

Question/Poll: Do you prefer `changelog.md` or the releases tool built into github (IE: https://github.com/evantahler/actionhero/releases https://github.com/evantahler/actionhero/releases).

hobarrera 12y ago
My reply below [1] talks about the pitfalls of the releaes too a bit. There's several other comments surrounding it already. That said, I feel that changelogs are way better, being more flexible and more in control of the user. I do feel that a lot of people can't keep one that well though. We don't need fine-grained details of every internal code refactor on a major-release changelog, since it's only relevant to devs (and they'll usually see the commit logs anyway). [1]: https://news.ycombinator.com/item?id=9237398 https://news.ycombinator.com/item?id=9237398
- skywinder 12y ago
  > We don't need fine-grained details of every internal code refactor - Thats why you shouldn't dump commit messages to logs! > since it's only relevant to devs Since you are hosting your project on GitHub - you are expecting, that it not only for end-users, and for Developers also, huh? So, why not to maintain neat change log for them? (And use GitHub Releases for end-users change log, without "fine-grained details of every internal code refactor")
insin 12y ago
Both: keeping a changelog and copying a section to the latest relase after tagging it, since they're both Markdown.
- skywinder 12y ago
  Yep. I would like to implement it also: https://github.com/skywinder/github-changelog-generator/issues/56 https://github.com/skywinder/github-changelog-generator/issu...

farslan 12y ago

This is very nice. I was creating manual changelog via Github releases. I really like that way because I can see the latest changes immediately and pick the relevant changes: https://github.com/fatih/vim-go/releases https://github.com/fatih/vim-go/releases

jonperl 12y ago

Very cool. We have been building a slack bot to do something similar, for internal release notes https://github.com/DispatchMe/meteor-rosie https://github.com/DispatchMe/meteor-rosie

mikegerwitz 12y ago

For those looking to generate changelogs, but not from issues or something GitHub-specific, gnulib has a tool to generate changelogs from commit messages: http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=build-aux/gitlog-to-changelog http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=bu...

skywinder 12y ago
>Dumping a diff of commit logs. Just don’t do that, you’re helping nobody. (c)https://github.com/olivierlacan/keep-a-changelog https://github.com/olivierlacan/keep-a-changelog It's very hard to maintain it in a good maner. The Issues fits for this purpose much better. (JMHO)

RandomBK 12y ago

I see this being very useful for generating a rough draft for the changelog that you can then edit and elaborate on. I find that not all commits change public facing APIs, so it would still be necessary go go over it and remove internal changes.

alfonsodev 12y ago

In the projects I work we prefix every commit with codename and 3 digits, I extract the change log from this command: git log v0.3...v0.4 --oneline | grep -oh -B 1 "CODENAME-[0-9][0-9][0-9]" | sort | uniq

skywinder 12y ago
I will add this feature in the future to this script also! https://github.com/skywinder/github-changelog-generator/issues/51 https://github.com/skywinder/github-changelog-generator/issu...

hiroshi3110 12y ago

I have used similar tool called `git-pr-release` which create release PR from bunch of topic PRs. I added a function that create a Github release from release PRs. https://github.com/hiroshi/git-pr-release/tree/create_release#the---release-flag https://github.com/hiroshi/git-pr-release/tree/create_releas...