Re:Generate Your Changelog From GitHub Issues
by scrapcode on Friday March 20, 2015 @08:08AM
(#9237150)
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".
Re:Generate Your Changelog From GitHub Issues
by akerl_ on Friday March 20, 2015 @08:28AM
(#9237226)
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.
Re:Generate Your Changelog From GitHub Issues
by tych0 on Friday March 20, 2015 @09:58AM
(#9237726)
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.
Re:Generate Your Changelog From GitHub Issues
by impostervt on Friday March 20, 2015 @08:16AM
(#9237189)
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.
Re:Generate Your Changelog From GitHub Issues
by evantahler on Friday March 20, 2015 @09:05AM
(#9237381)
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
Re:Generate Your Changelog From GitHub Issues
by RandomBK on Friday March 20, 2015 @09:57AM
(#9237715)
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.
Re:Generate Your Changelog From GitHub Issues
by zimbatm on Friday March 20, 2015 @08:04AM
(#9237141)
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-changel...
Re:Generate Your Changelog From GitHub Issues
by rlpb on Friday March 20, 2015 @08:08AM
(#9237153)
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.
Re:Generate Your Changelog From GitHub Issues
by hobarrera on Friday March 20, 2015 @09:09AM
(#9237398)
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`.
Re:Generate Your Changelog From GitHub Issues
by mercurial on Friday March 20, 2015 @08:22AM
(#9237210)
> 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.
Re:Generate Your Changelog From GitHub Issues
by tenfingers on Friday March 20, 2015 @12:38PM
(#9238696)
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.
Re:Generate Your Changelog From GitHub Issues
by mikegerwitz on Friday March 20, 2015 @09:45AM
(#9237637)
For those looking to generate changelogs, but not from issues or something GitHub-specific, gnulib has a tool to generate changelogs from commit messages:
Re:Generate Your Changelog From GitHub Issues
by farslan on Friday March 20, 2015 @09:25AM
(#9237503)
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:
Re:Generate Your Changelog From GitHub Issues
by tonyhb on Friday March 20, 2015 @08:29AM
(#9237233)
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.
Re:Generate Your Changelog From GitHub Issues
by skywinder on Friday March 20, 2015 @08:42AM
(#9237278)
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.
Re:Generate Your Changelog From GitHub Issues
by hobarrera on Friday March 20, 2015 @09:13AM
(#9237429)
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).
Re:Generate Your Changelog From GitHub Issues
by skywinder on Friday March 20, 2015 @07:39PM
(#9241310)
> 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")
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".
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.
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-changel...
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.
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`.
Personally, I wouldn't want to go to Github every time I download a new version of a library. Text files are fine.
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.
http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=bu...
It's very hard to maintain it in a good maner. The Issues fits for this purpose much better. (JMHO)
https://github.com/fatih/vim-go/releases
Do you prefer `changelog.md` or the releases tool built into github (IE: https://github.com/evantahler/actionhero/releases).
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
- 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")
git log v0.3...v0.4 --oneline | grep -oh -B 1 "CODENAME-[0-9][0-9][0-9]" | sort | uniq