Changelogs are noisy

[domenic]

I have a few complaints about the changelogs and was wondering if anyone shared them. In order of decreasing importance:

• npm takes up half or more of the headlining "notable changes" space. I think it should get a budget of one sentence, and the rest can be links to the one or more npm changelog entries.
• known issues is incomplete and repetitive. Pretty much all of the 19 issues tagged as bug count as "known issues". Probably others do too. And this section just stays the same release after release. Can we replace it with a link to the bug tag (or to a new known issues tag, if there's some distinction I'm missing between them)? If we need a snapshot of issues at a given point in time, can we collapse it into a single list like "Known issues: #x, #y, #z" instead of summarizing them over and over?
• The commits list seems a bit redundant. Could we just link to the GitHub compare tags view? That way people can more easily expand to see the whole commit message.

I say all this with love, as the readable changelogs are one of the best parts of io.js :). I just want to make them a bit more usable.

[Fishrock123]

If we need a snapshot of issues at a given point in time, can we collapse it into a single list like "Known issues: #x, #y, #z" instead of summarizing them over and over?

Hmm, something like that may be worthwhile, question is still though, what do and don't we put there? We clearly can't link the entire issue tracker.

(Also I think a sort of vs node mentality comes in a bit. Lots of these issues node also has though.)

[domenic]

what do and don't we put there? We clearly can't link the entire issue tracker.

Right, well in a previous thread you mentioned "not all issues are bugs," and so I poked around and came to the conclusion that maybe the "bug" tag would be the trick. There's only 19 of them right now, and a 19-item inline list of numbers (no line breaks) is not so bad.

[chrisdickinson]

Having some documentation around what we'd like out of a good changelog would be helpful as well. A document at /doc/writing-changelogs.md linked to from /api/releases.md would be a nice, actionable way to codify these changes!

[mikeal]

When we do the weekly updates we tend to condense the information about them in to a more human readable form that is quicker to get the gist of.

[rvagg]

@mikeal what does that condensation process look like? Are we too wordy in the notable items?

Re the npm section, note that it's only a few notable items from their changelog that @othiym23 pulls out and feels are important to highlight, usually I try not to have a strong opinion on what people need to know about npm changes so perhaps this is feedback for him to try and keep it a bit shorter.

Re known issues ... shrug, I can see that I started this in 1.0.3, I'm not sure why I felt compelled to, but I continued doing it after @chrisdickinson did the same in 1.1.0 so I guess we fed off each other there. I quite like the fact that we're open about serious problems but the repetitive nature gets to me a bit since it's not actually leading to much action on them (like I thought it might) and also, as pointed out, the line is kind of grey around what goes in there or not. I won't resist dropping it if the feeling is strong enough. (@piscisaureus we need that collaborator voting mechanism so we can collect opinions on things like this).

[mikeal]

@rvagg well, the full changelog is usually longer than we like the entire weekly update to be. we don't talk about any of the bugfixes and we take any new features and highlevel items and reduce them to no more than one sentence a piece.

[othiym23]

I try to keep the npm chunk to two or three items at most, and there's been a lot of notable changes in npm lately, so I wouldn't want to make it too mush shorter. If it's still too much space, just link to npm's CHANGELOG.md – the individual releases are anchors in the rendered Markdown.

FWIW, the feedback I get on the npm release notes is uniformly positive. People seem to really like the level of detail.

[Fishrock123]

I try to keep the npm chunk to two or three items at most,

yes, that last update was a little larger than usual with all the git fixes and what.

[domenic]

Yeah, the npm changelogs are great, just not having them directly in the io.js changelogs would be nice. I'm thinking:

npm: upgrade from 2.7.6 to 2.8.3. Fixes to Git-URL dependencies and scoped packages. Details: 2.8.0, 2.8.1, 2.8.2, 2.8.3

[piscisaureus]

@piscisaureus we need that collaborator voting mechanism so we can collect opinions on things like this

OK - taking a stab at it.

[rvagg]

As a counterpoint to the "changelogs are too noisy" complaint, I'd like to record that even though my name is on most of these new entries I've never received a comment about them being too noisy or verbose, in fact I've got a lot of comments about just the opposite, like this on DailyJS (one of multiple comments that have been made there about the new changelog style):

io.js 1.8.1 has been released. As always the changelog is concise and informative. You might want to update to this release if you use npm's new scoped modules

When I started doing this my intention was to provide something much more human-readable than what we were used to seeing with Node.js changelogs because I was sick of having to click through commits to figure out what was actually important or not. The fact that most of our releases are much bigger in terms of number of commits than a standard Node.js release just compounds this problem. To me, the changelog is more about the "notable changes" section than the commit log.

[mikeal]

I like them as is, we have a condesned version for the weekly update if
people want something simpler.

On Friday, April 24, 2015, Rod Vagg notifications@github.com wrote:

As a counterpoint to the "changelogs are too noisy" complaint, I'd like to
record that even though my name is on most of these new entries I've never
received a comment about them being too noisy or verbose, in fact I've got
a lot of comments about just the opposite, like this on DailyJS
http://dailyjs.com/2015/04/22/node-roundup-io-js-1-8-1-ioredis-fetchival/
(one of multiple comments that have been made there about the new changelog
style):

io.js 1.8.1 has been released. As always the changelog is concise and
informative. You might want to update to this release if you use npm's new
scoped modules

When I started doing this my intention was to provide something much more
human-readable than what we were used to seeing with Node.js changelogs
because I was sick of having to click through commits to figure out what
was actually important or not. The fact that most of our releases are much
bigger in terms of number of commits than a standard Node.js release just
compounds this problem. To me, the changelog is more about the "notable
changes" section than the commit log.

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