Change log

[strugee]

This project could use a change log. GitHub Releases seems to be used sporadically? But not all the entries are there and those that are aren't very detailed. So a proper change log would be nice.

<3

See http://keepachangelog.com

[anantnema]

its a good idea to include a change log...!! (y)

[dcodeIO]

But, for which recent changes? This package is mostly in maintenance mode and the commit history is quite overseeable nowadays.

[strugee]

@dcodeIO the package is at major version 2. I'd like to know what changed between those versions. I'd also like a broad overview of how the project has progressed over time, but that's less important than the semver-major changes.

As for the commit history, I like what http://keepachangelog.com says:

Why can’t people just use a git log diff?

Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states.

As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.

[dcodeIO]

I like what http://www.urbandictionary.com/define.php?term=smarty%20pants says

[strugee]

@dcodeIO uh... I'm sorry? I don't know how you found my comment rude but I was just trying to answer your question. That's all.

[julianlam]

I find it a bit ironic that this reply chain lands in my inbox the same week GitHub's open source survey results come out identifying rudeness and name calling being the most common negative reactions encountered by contributors.

As an outsider looking in, let's be civil shall we? @dcodeIO I appreciate your project. If there are no breaking changes between v1 and v2, should be simple to call that out in the readme.

[dcodeIO]

I actually intended to be a bit rude there, as it is a bit rude feels annoying to be educated that a git commit history isn't a change log - twice. No worries, though, it's all happening in a controlled environment and I know that you / he didn't mean to offend anyone. Sorry for that!

Back to topic: I certainly understand that every project should have a change log. I was just wondering about the timing because nothing really happens here. I'll add one with the next change, if necessary, or you can go ahead and contribute one.

[strugee]

@dcodeIO I really don't know how to respond to that. How in the world is educating someone else rude? I for one really like learning new things and having my perspectives challenged. I've been programming for five years and would consider myself a relatively "seasoned" programmer, but I still have a huge amount to learn. I just honestly can't understand your position.

Was it because I said it twice? I said it twice because you explicitly asked about the commit history, so I pulled a quote from a resource I'd already linked to. The question was already answered. Was I supposed to just not answer your question?

Maybe there's a cultural difference here?

In any case, I don't think I personally have the bandwidth to go through and write up a change log. But it'd be awesome if someone else did.

[dcodeIO]

Sorry, "rude" wasn't the correct term there. I meant "annoying".

[dcodeIO]

@strugee: I want to emphasize again that my comment(s) above was unprofessional and unnecessary. I appreciate that you are trying to improve this package. Keep up your enthusiasm for open source software!

[strugee]

@dcodeIO thanks for saying that! I feel for you - I've had bad days as a maintainer too.

So no hard feelings :)

[Ruffio]

I think this issue/suggestion should be closed? I don' think there will come a change log as it has a very low priority.