👍

Hey @skywinder, thanks for the pull request.

github_changelog_generator is an interesting project, and I like the goal of making it easier for open source projects to provide high-quality documentation for changes in a project.

I'm less excited about adopting this format for the Overcommit project at this point in time. Some quick reasons:

• There is a lot of "air" (unnecessary blank lines) in the resulting output, which there doesn't appear to be a flag to control. I could write a script that does some post-processing to correct this to my desire, however.
• I would like tighter control over the markup used (e.g. using headings instead of <strong> tags via **..** Markdown). This is solvable by passing an ERB file (or any template format) describing the desired format, but that is not a feature currently supported. I could also do some post-processing in a separate script.
• Even with the --exclude-labels option, there is still a lot of noise for the Overcommit project (lots of issues with incorrect labels). This can be fixed by making a pass at re-labelling everything in the project, but that will take some time and I can't say I'm terribly excited about the idea.
• In order to make the changelog more readable, I will also have to go through and rename issues/pull requests so that they read sensibly when inserted in the changelog (the format of changelog entries is structured so that all changes start with a verb in the imperative form, which is good practice). I'm also not excited by the thought of this work.

Having said all that, were none of these an obstacle I would be excited to utilize this tool for generating changelog entries automatically. I applaud your efforts to make it easier for open source maintainers to maintain better documentation for the changes in tools. Given that the Overcommit project (in my opinion) has a clear, concise changelog without information overload, I don't see this as something we need to address just yet, but I would like to address it in future.

I would also love to be able to adopt this format going forward, rather than take it on wholesale (as it would avoid a lot of the problems mentioned above). It looks like implementing github-changelog-generator/github-changelog-generator#211 would solve this issue, so once that is implemented we can revisit this topic.

@sds Thank you for great description and review. I very appreciate that!

1. Can you clarify, which of blank line is "unnecessary"? I agree with you, it can be more compact.

2. about converting all markdown syntax to html tags - you're right. I believe, that should be formatters, that can convert markdown syntax to html.
   It can be implemented as a feature, if there is will be another requests for such option.

Even with the --exclude-labels option, there is still a lot of noise for the Overcommit project.

Can you provide example of such "noise issues"? And I will try to figure out how to handle it.

This can be fixed by making a pass at re-labelling everything

No way! This genereator is tend to eliminate any special actions from the user (even in case when issues labels filled correctly (like in yours repo).

And finally, about renaming - yes, it's hardest part, but if you will pay attention to maintain it a little bit (even for important issues, that should appear in change log) - it will not be a problem anymore.

Ok, I will let you know,when I will implement github-changelog-generator/github-changelog-generator#211. 😉
For now- you can try to run github_changelog_generator --unreleased-only before place a tag and have ability to get a quick brief, which issues was closed since last version.

And finally, your change log get me one more idea, how to make it better. Look at github-changelog-generator/github-changelog-generator#241 it will help you to not break your change log format.

Regarding 2) Sorry, I didn't mean supporting HTML output. I mean that right now the different headings are output with a specific markdown format, e.g.

Implemented enhancements

versus:

Implemented Enhancements

Again, this is a small point, but it is solvable by allowing arbitrary templates.

Regarding "noise", I'm referring to issues like this: https://github.com/skywinder/overcommit/blame/add-change-log-file/CHANGELOG_AUTO.md#L29

In my mind, this isn't something that needs to be communicated to users of the tool in a change log (it doesn't reflect a change in behavior of the tool itself, but is merely a change in documentation). This can be solved by relabeling that issue with a label like chore or something else, so it doesn't show up under enhancements (so not an issue with your tool, but another reason why relabelling all the issues would be necessary).

However, if github-changelog-generator/github-changelog-generator#211 is implemented, then we can easily adopt this new format going forward without having to deal with relabelling old issues.

1. according spaces - yep, they doesn't make sense in markdown output, but it's quite easy to read raw file with this spaces. I will make an option to disable it.
2. Yes, I also thinking about such improvement. I added issue for that ability Arbitrary templates github-changelog-generator/github-changelog-generator#242
3. regarding "noise" issues - the more suitable solution for such issues - is just add tag wontfix (or smth like chore) for example. You're right.

BDW:
You can put more, than 1 tag per issue. And excluded labels have more priority than included.
So if generator find issue with one of "included" and "excluded" labels together - it exclude this issue.

Ok, since 1.6.1 you can set custom labels for sections:

For your chane log format the script should be running with this options:

github_changelog_generator --bugs-label "Bug Fixes" --enhancement-label "New Features" --issues-label "Changes"