doc: add per-item changelogs #11489

addaleax · 2017-02-22T00:43:37Z

Add per-item changelogs to the docs, for notable changes to the API made between io.js 1.0.0 and now. I have used a somewhat subjective idea of “notable” and focused on changes in how the API is used rather than e.g. bug fixes, so please feel free to point out anything that you feel is missing here or doesn’t belong here.

Also, in cases of LTS backports I’ve listed all versions in which the change was applied.

Example screenshot:

/cc @nodejs/documentation @nodejs/collaborators

mscdex · 2017-02-22T00:47:29Z

I think this table should be collapsible and be collapsed by default, especially since it sits in between the current syntax and its parameters and it takes up a fair amount of space (even more so as time goes along).

addaleax · 2017-02-22T00:59:51Z

@mscdex Good idea, done!

italoacasas · 2017-02-22T01:09:52Z

Wao really nice idea...

Maybe the Added in can be the first row in the table?

joyeecheung · 2017-02-22T01:11:12Z

Great work!

What about future changes, how will they be added in the documentation? Along with backport PRs?

addaleax · 2017-02-22T01:12:55Z

What about future changes, how will they be added in the documentation? Along with backport PRs?

Just like we currently handle the added: tags – you add an entry like these containing a REPLACEME tag to the documentation, which will then replaced by the actual version during the release.

Backport PRs might require a bit of manual work by the releaser but that should be okay given how few significant API changes we actually backport.

mscdex · 2017-02-22T01:23:26Z

Something else to think about is at what point do we start removing ancient version information (if we should decide that)? If we don't, some of the pages could get quite long unless we set a max height on the tables, at which point the table could automatically be scrollable.

addaleax · 2017-02-22T01:34:22Z

@italoacasas Done! See updated screenshot.

Something else to think about is at what point do we start removing ancient version information (if we should decide that)? If we don't, some of the pages could get quite long unless we set a max height on the tables, at which point the table will be scrollable.

@mscdex I doubt that will happen anytime soon. I don’t think any entry here has more than 3 changelog entries (4, counting the Added in … one).

italoacasas · 2017-02-22T03:59:57Z

@addaleax I think the word Added in the right column is enough, but since English is not my native language maybe another word to describe the idea?

addaleax · 2017-02-22T13:14:50Z

@italoacasas Not sure, I’m not a native English speaker either. If anybody else has better suggestions I’ll gladly take them.

jasnell

Love it. Thank you for this. It'll be a bit of work to keep things updated but really quite valuable

sam-github · 2017-02-22T17:46:22Z

This is great. I agree it would be good to have the table be collapsible, and default to collapsed.

Agree that changes in the API usage (equiv of semver-minor and -major) are what should be documented, not bug fixes.

I would suggest "History" as a less jargony alternative to "Changelog".

silverwind · 2017-02-22T22:36:34Z

Few stylistic suggestions. Maybe add a class to <details> to allow more targeted styling.

details > summary {
  margin: .5rem 0;
  padding: .5rem 0;
  cursor: pointer;
}

addaleax · 2017-02-23T13:29:35Z

@silverwind Done, see updated screenshot

I would suggest "History" as a less jargony alternative to "Changelog".

@sam-github Done, sounds better to me too

silverwind · 2017-02-23T16:40:51Z

doc/api_assets/style.css

@@ -470,6 +470,12 @@ th > *:last-child, td > *:last-child {
  margin-bottom: 0;
 }

+details > summary {


.changelog > summary would be better now that we have a class :)

@silverwind done – sorry, wasn’t 100 % sure whether you meant that ;)

bnoordhuis

Nice, LGTM with some comments/questions.

bnoordhuis · 2017-02-23T16:44:58Z

doc/api/buffer.md

+changes:
+  - version: v3.0.0
+    pr-url: https://github.com/nodejs/node/pull/2002
+    description: The `Buffer`s class now inherits from `Uint8Array`.


Should this be in  markers or do I misunderstand how it works?

bnoordhuis · 2017-02-23T16:46:40Z

doc/api/os.md

+changes:
+  - version: v5.11.0
+    pr-url: https://github.com/nodejs/node/pull/6093
+    description: Added support for `SIGINFO`.


bnoordhuis · 2017-02-23T16:52:10Z

tools/doc/html.js

+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  a = a.substr(i);
+  b = b.substr(i);
+  return +b.match(numberRe)[1] - +a.match(numberRe)[1];


This is going to fail with a TypeError on malformed input (e.g. v0.12.x.) Is that acceptable?

@bnoordhuis I actually couldn’t get this code to fail, it would just treat v0.12.x as 0 (assuming the common prefix is v0.12.). That seems somewhat reasonable to me.

Oh, the capture is for zero or more digits (star, not plus.) Right, that never fails to produce a match object. Please disregard then.

addaleax · 2017-02-23T17:08:34Z

Updated, thanks for catching these.

CI: https://ci.nodejs.org/job/node-test-commit/8097/

PR-URL: nodejs#11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

PR-URL: #11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

PR-URL: nodejs#11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

PR-URL: #11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

Notables changes: * child_process: spawnSync() exit code now is null when the child is killed via signal (cjihrig) [nodejs#11288](nodejs#11288) * http: new functions to access the headers for an outgoing HTTP message (Brian White) [nodejs#11562](nodejs#11562) * lib: deprecate node --debug at runtime (Josh Gavant) [nodejs#11275](nodejs#11275) * tls: new tls.TLSSocket() supports sec ctx options (Sam Roberts) [nodejs#11005](nodejs#11005) * url: adding URL.prototype.toJSON support (Michaël Zasso) [nodejs#11236](nodejs#11236) * doc: items in the API documentation may now have changelogs (Anna Henningsen) [nodejs#11489](nodejs#11489) PR-URL: nodejs#11553

Notables changes: * child_process: spawnSync() exit code now is null when the child is killed via signal (cjihrig) [nodejs#11288](nodejs#11288) * http: new functions to access the headers for an outgoing HTTP message (Brian White) [nodejs#11562](nodejs#11562) * lib: deprecate node --debug at runtime (Josh Gavant) [nodejs#11275](nodejs#11275) * tls: new tls.TLSSocket() supports sec ctx options (Sam Roberts) [nodejs#11005](nodejs#11005) * url: adding URL.prototype.toJSON support (Michaël Zasso) [nodejs#11236](nodejs#11236) * doc: items in the API documentation may now have changelogs (Anna Henningsen) [nodejs#11489](nodejs#11489) * crypto: adding support for OPENSSL_CONF again (Sam Roberts) [nodejs#11006](nodejs#11006) * src: adding support for trace-event tracing (misterpoe) [nodejs#11106](nodejs#11106) PR-URL: nodejs#11553

Notables changes: * child_process: spawnSync() exit code now is null when the child is killed via signal (cjihrig) [#11288](nodejs/node#11288) * http: new functions to access the headers for an outgoing HTTP message (Brian White) [#11562](nodejs/node#11562) * lib: deprecate node --debug at runtime (Josh Gavant) [#11275](nodejs/node#11275) * tls: new tls.TLSSocket() supports sec ctx options (Sam Roberts) [#11005](nodejs/node#11005) * url: adding URL.prototype.toJSON support (Michaël Zasso) [#11236](nodejs/node#11236) * doc: items in the API documentation may now have changelogs (Anna Henningsen) [#11489](nodejs/node#11489) * crypto: adding support for OPENSSL_CONF again (Sam Roberts) [#11006](nodejs/node#11006) * src: adding support for trace-event tracing (misterpoe) [#11106](nodejs/node#11106) PR-URL: nodejs/node#11553 Signed-off-by: Ilkka Myller <ilkka.myller@nodefield.com>

addaleax · 2017-03-05T22:21:00Z

@italoacasas Just so you know, I added the dont-land-on-v7.x label back, there is a commit in here that should not land on v7.x

addaleax added doc Issues and PRs related to the documentations. tools Issues and PRs related to the tools directory. labels Feb 22, 2017

addaleax force-pushed the changelogs branch from 683f5d6 to fe52138 Compare February 22, 2017 00:59

addaleax force-pushed the changelogs branch from fe52138 to b01dcc6 Compare February 22, 2017 01:32

jasnell approved these changes Feb 22, 2017

View reviewed changes

sam-github approved these changes Feb 22, 2017

View reviewed changes

addaleax force-pushed the changelogs branch 2 times, most recently from 2cfbc79 to a8ad747 Compare February 23, 2017 13:28

silverwind reviewed Feb 23, 2017

View reviewed changes

addaleax force-pushed the changelogs branch from a8ad747 to 130a1b4 Compare February 23, 2017 16:43

bnoordhuis approved these changes Feb 23, 2017

View reviewed changes

addaleax force-pushed the changelogs branch from 130a1b4 to 8c13b91 Compare February 23, 2017 17:07

italoacasas approved these changes Feb 23, 2017

View reviewed changes

silverwind approved these changes Feb 23, 2017

View reviewed changes

addaleax added 3 commits February 24, 2017 02:06

doc: add changelogs for assert

a0af305

PR-URL: nodejs#11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

doc: add changelogs for buffer

7b6e302

PR-URL: nodejs#11489 Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl> Reviewed-By: Sam Roberts <vieuxtech@gmail.com> Reviewed-By: Roman Reiss <me@silverwind.io> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Italo A. Casas <me@italoacasas.com>

addaleax mentioned this pull request Feb 24, 2017

(v7.x) doc: backport “fix sorting in API references”, “add changelogs for {v8,buffer}” #11529

Closed

italoacasas removed the dont-land-on-v7.x label Feb 28, 2017

italoacasas mentioned this pull request Feb 28, 2017

7.7.0 Proposal #11553

Merged

addaleax added the dont-land-on-v7.x label Mar 5, 2017

jasnell mentioned this pull request Apr 4, 2017

8.0.0 Release Proposal #12220

Closed

joyeecheung mentioned this pull request Apr 10, 2017

readdir docs don’t mention when options argument was added #12299

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add per-item changelogs #11489

doc: add per-item changelogs #11489

addaleax commented Feb 22, 2017 •

edited

Loading

mscdex commented Feb 22, 2017 •

edited

Loading

addaleax commented Feb 22, 2017

italoacasas commented Feb 22, 2017

joyeecheung commented Feb 22, 2017

addaleax commented Feb 22, 2017

mscdex commented Feb 22, 2017 •

edited

Loading

addaleax commented Feb 22, 2017

italoacasas commented Feb 22, 2017 •

edited

Loading

addaleax commented Feb 22, 2017

jasnell left a comment

sam-github commented Feb 22, 2017

silverwind commented Feb 22, 2017

addaleax commented Feb 23, 2017

silverwind Feb 23, 2017

addaleax Feb 23, 2017

bnoordhuis left a comment

bnoordhuis Feb 23, 2017

bnoordhuis Feb 23, 2017

bnoordhuis Feb 23, 2017

addaleax Feb 23, 2017

bnoordhuis Feb 23, 2017

addaleax commented Feb 23, 2017

addaleax commented Mar 5, 2017

doc: add per-item changelogs #11489

doc: add per-item changelogs #11489

Conversation

addaleax commented Feb 22, 2017 • edited Loading

mscdex commented Feb 22, 2017 • edited Loading

addaleax commented Feb 22, 2017

italoacasas commented Feb 22, 2017

joyeecheung commented Feb 22, 2017

addaleax commented Feb 22, 2017

mscdex commented Feb 22, 2017 • edited Loading

addaleax commented Feb 22, 2017

italoacasas commented Feb 22, 2017 • edited Loading

addaleax commented Feb 22, 2017

jasnell left a comment

Choose a reason for hiding this comment

sam-github commented Feb 22, 2017

silverwind commented Feb 22, 2017

addaleax commented Feb 23, 2017

silverwind Feb 23, 2017

Choose a reason for hiding this comment

addaleax Feb 23, 2017

Choose a reason for hiding this comment

bnoordhuis left a comment

Choose a reason for hiding this comment

bnoordhuis Feb 23, 2017

Choose a reason for hiding this comment

bnoordhuis Feb 23, 2017

Choose a reason for hiding this comment

bnoordhuis Feb 23, 2017

Choose a reason for hiding this comment

addaleax Feb 23, 2017

Choose a reason for hiding this comment

bnoordhuis Feb 23, 2017

Choose a reason for hiding this comment

addaleax commented Feb 23, 2017

addaleax commented Mar 5, 2017

addaleax commented Feb 22, 2017 •

edited

Loading

mscdex commented Feb 22, 2017 •

edited

Loading

mscdex commented Feb 22, 2017 •

edited

Loading

italoacasas commented Feb 22, 2017 •

edited

Loading