Add CHANGELOG

[cesarandreu]

Updating from 5.1.x to 5.2.x causes my app to break in a few places. I'm fine with with fixing those, but having a CHANGELOG where I can see the changes makes it easier to know what I'll be hunting down.

[dcousens]

@cesarandreu could you comment on what breaks you experienced?

[Flet]

Indeed I think a changelog might be helpful.

All the rule changes are captured on eslint-config-standard

[Flet]

https://github.com/feross/eslint-config-standard/commits/master anything beyond 4.1.0 is probably what affected you.

[cesarandreu]

I got the following new errors / warnings:

• Block must not be padded by blank lines.
• '?' should be placed at the beginning of the line.
• ':' should be placed at the beginning of the line.
• Requires a space before "}".
• Infix operators must be spaced.

[yoshuawuyts]

Perhaps https://github.com/rvagg/changelog-maker could be useful for generating changelogs.

[dcousens]

Block must not be padded by blank lines.

This was a long standing rule that was broken in eslint for a small while. It was technically always a standard idiom.

Requires a space before "}".

There is a requirement for even/consistent spacing, is this what you mean?

Infix operators must be spaced.

Elaborate?

[Flet]

Ah cool, I did not know this existed, @yoshuawuyts :) It looks like its a piece of the puzzle for adding to the node.js changelog (their release instructions have the full details)

I'm currently hand-crafting a changelog with the last couple releases just to get something out here (using vmd to preview as I craft them 😉). I'll post them in the node.js format above and we can gather feedback from folks.

[Flet]

Actually, I am leaning towards something simpler like the format proposed at http://keepachangelog.com/

[Flet]

Added a changelog:
https://github.com/feross/standard/blob/master/CHANGELOG.md

It follows http://keepachangelog.com/ conventions. I decided to not list the raw commits and instead tried to make the change log more human readable.

A lot of standard is now broken out into dependencies, so a link to the dependency's CHANGELOG/history is provided along with a list of changes that affected standard.

There is also some redundancy; if a dependent package had "Fixed" and "Added" things, its shown twice with a specific list of things for each section. I feel this adds some clarity, especially if there are multiple changes in a dependency.

If you have time, please take a look and give some feedback! Thanks!

(would love feedback from @ngoldman and @bcomnes too!)

[bcomnes]

Awesome CHANGELOG work @Flet Looks great.

If a change is only supposed to be a minor, but in reality turns out to be major, it might be grounds for a re-versioned release with a deprecate on the incorrect semver bump (at least in theory, I've never actually gone through this process).

[yoshuawuyts]

@Flet looks excellent!

[feross]

I'm usually not a fan of changelog files because they take extra effort to keep up-to-date and this is an all-volunteer effort already, but I do understand the need for end users to quickly find out what changed.

Let's try it out and see how it works.

[feross]

If a change is only supposed to be a minor, but in reality turns out to be major, it might be grounds for a re-versioned release

The ternary (? :) and the 'blocks must not be padded' rules have been part of standard even though they haven't been enforced consistently due to eslint bugs and ditching jscs at one point. But now that we can enforce them again, they're basically bugfixes, though it's true that users experience them as breaking changes.

Sorry about that folks -- hopefully won't happen again. I don't think we have any more of these.

[Flet]

Thanks @feross. I'll happily try to keep it up to date if folks forget 😇 The standard releases seem to be kept pretty small these days anyways, so that should make it easier to maintain.

[feross]

An 👼 indeed -- thanks!

[cesarandreu]

That was really quick, thanks!

[ungoldman]

@Flet: lgtm 👍

I'm a fan of the change log. I like to add a link to the diff between each release (e.g. 5.2.1 header links to v5.2.0...v5.2.1) but that's a lot of effort for a small reward. @bcomnes and I worked on some stuff related to change logs (https://github.com/bcomnes/changelog-init & https://github.com/ngoldman/gh-release) and I've wanted to create something to automate adding those diff links. Maybe I'll take a crack at that this week.

@feross: re:

I'm usually not a fan of changelog files because they take extra effort to keep up-to-date and this is an all-volunteer effort already, but I do understand the need for end users to quickly find out what changed.

I understand it can be a bit of a chore, but it definitely helps keep contributors and collaborators more aware of user-facing changes and makes it easier to make a call about patch vs. minor vs. major releases. If it's just a small part of each contribution it starts to take care of itself. :)

[ungoldman]

@bcomnes I've gone through the process you described above, it's not that bad. Just npm publish the major version and npm deprecate pkg@x.y.z "warning message" and that message will show up on npm install if anyone's still installing that version. Definitely a bad scenario for users though, which I think keeping a change log helps avoid.

[Flet]

Nice, love the diff link idea. I went ahead and added them (plus diff links going back to 4.0.0).

[feross]

The diff links are handy!