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...
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".
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.
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.
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
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.
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.
> 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.
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`.
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.
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.
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.
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).
> 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 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:
For those looking to generate changelogs, but not from issues or something GitHub-specific, gnulib has a tool to generate changelogs from commit messages:
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.
37 comments
[ 3.2 ms ] story [ 79.9 ms ] threadThe `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...
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.
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.
Personally, I wouldn't want to go to Github every time I download a new version of a library. Text files are fine.
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`.
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.
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")
https://github.com/fatih/vim-go/releases
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)
git log v0.3...v0.4 --oneline | grep -oh -B 1 "CODENAME-[0-9][0-9][0-9]" | sort | uniq