Adopt manual style of updating CHANGES.md

[mjackson]

I realize that this flies in the face of everything we believe in as computer programmers, but I'd really like to just adopt a manual process of updating CHANGES.md like we do in https://github.com/rackt/history. Here's why:

• I think https://github.com/rackt/history/blob/master/CHANGES.md is more fun to read than https://github.com/rackt/react-router/blob/master/CHANGELOG.md
• rf-changelog (the tool we currently use to generate CHANGELOG.md) doesn't recognize more than one [changed] or [fixed] line from a single commit

The only extra thing we'd need to do in this repo is update our CONTRIBUTING.md to kindly ask people to add an entry to CHANGES.md when submitting a PR.

[knowbody]

👍 sounds good to me!

The only extra thing we'd need to do in this repo is update our CONTRIBUTING.md to kindly ask people to add an entry to CHANGES.md when submitting a PR.

or we can do it after the merge

[taion]

It's also really easy to forget to format your commit subject appropriately.

That said, my first preference would be to do everything through PRs and generate changelog from PR titles, though. Dunno if that'd work.

[mjackson]

That's a great idea, @taion. It will require plugging in to the GirHub API,
so it will take a bit more work, but I think it could work at some point in
the future.
On Tue, Oct 27, 2015 at 5:55 PM Jimmy Jia notifications@github.com wrote:

It's also really easy to forget to format your commit subject
appropriately.

That said, my first preference would be to do everything through PRs and
generate changelog from PR titles, though. Dunno if that'd work.

—
Reply to this email directly or view it on GitHub
#2399 (comment)
.

[gaearon]

I prefer writing changelog manually because I can prioritize important / non-important changes, and I also use it as upgrade guide, showing “before” and “after” for every breaking change. In fact instead of maintaining a changelog, I just point people to the Releases page where every release has manually written notes.

[taion]

Some discussion elsewhere about generating changelogs from merged PRs, with links to packages for doing this: react-bootstrap/react-bootstrap#534

I think it might make sense to have both a changelog and separate release notes. One to be a comprehensive list of all the changes (in a format slightly more approchable than a commit log), the other as @gaearon has above.

[mjackson]

In general, I think auto-generating a changes document is eventually going to be problematic. Instead, if we just require every PR to also add a line or two to the changes doc we'll be good.

Eventually I'd like to put our upgrade guide in the changes doc as well, but one thing at a time :)

[ryanflorence]

I'm with @mjackson, just edit it manually. Instead of an auto generated change log lets just do all API changing commits in a pull request with these rules on the pull request:

1. Any changed API must be documented in the upgrading guide
2. It must include an entry in the changelog
3. It must include updates to current api documentation and guides
4. It must include updates to the examples so they aren't busted

The big surprise here is that I manually updated changlelog with nearly every release, the script merely served to let me know what API changed, since I wasn't the only one writing code but was generally the only one writing the docs, examples, upgrading guide, and changelog.

Now the job of updating documentation, examples, the upgrading guide, and the changelog is on the person changing the API.

or we can do it after the merge

let's keep it in the pull request, if its after the merge it won't happen every time but it needs to.