Release notes / Change log for project

[zeroclipboard]

Release notes / Change log for project

[jonrohan]

That would be excellent, do you have any tips or techniques for making it automated?

[JamesMGreene]

The only effort-efficient way that comes to mind is just generating it from the commit logs. This, however, requires that we keep our commit history clean: rebase away the merge commits, squash/fixup superfluous commits into a single-purpose commit (e.g. feature/topic branch commits like in PRs), write good commit messages that mention if their changes might break backward compatibility, etc.

Perhaps the project leads for some other big projects (jQuery, Grunt, PhantomJS, etc.) could give us alternate suggestions. @dmethvin @scottgonzalez @cowboy @ariya?

[jonrohan]

squash commits, and rebases sound horrible, I'd rather write text each release.

[JamesMGreene]

Squashes and rebases aren't exactly fun but they certainly aren't needed all the time and they serve a very important purpose in keeping the history clean... and THAT is very important for hunting down regressions, etc,., as with git bisect. You should probably learn to embrace them as a GitHubber. 😛

[dmethvin]

There's no automated way to know which changes are significant and which are not, it's up to your intuition and the quality of the unit tests. For a sufficiently large installed base, every change is a breaking change regardless of whether the behavior is documented or not.

I'm a fan of squash, rebase -i, and --amend (before push) on commits to the main project. Without them the commit history gets way too messy on a large project. Landing kitchen-sink branches is hard no matter how you do it though.

@otakusid, "waiting until the bugs are fixed" may use less of your time, but it won't allow you to contribute to the project by helping find and fix problems. Someone has to do it. Get a new version and give constructive detailed feedback about what broke, or document what changed!

[jonrohan]

We already have https://github.com/jonrohan/ZeroClipboard/blob/master/docs/releases.md I'm gonna work on keeping it updated more frequently.

[scottgonzalez]

It really depends on how detailed you want your change logs to be. For jQuery UI, we actually look at every single commit. I wrote a script that dumps out the log for the version we're releasing, parses it for references to issues, and inserts links.

While I do prefer clean history and hate merge commits, you don't need to change your process to deal with them. If you're going to script any part of this, you can easily have the script remove any line that starts with "Merge".

If you're interested, here's the script that generates the jQuery UI changelog: https://github.com/jquery/jquery-ui/blob/master/build/release/release.js#L219 Though there's still a lot of manual work that goes into it after that, and the upgrade guides are 100% hand written.

[cowboy]

We've written an entire Upgrading from 0.3 to 0.4 migration guide for grunt.

[JamesMGreene]

@cowboy: That looks great, I'm a big fan of upgrade guides to explain breaking changes.