doc: add legacy status #37784

jasnell · 2021-03-17T19:43:10Z

Adds a new "Legacy" option to the stability index. The idea here is to give us another alternative to deprecating. Legacy code is still subject to semver rules but is specifically called out as legacy and to be avoided.

Marks the legacy URL parser as legacy, removing deprecated.

/cc @nodejs/tsc @addaleax @ljharb

ljharb

LGTM

doc/api/deprecations.md

mcollina

lgtm

doc/api/url.md

doc/api/deprecations.md

aduh95 · 2021-03-17T22:38:41Z

It could be worth also updating the other history sections so they are consistent:

It's also worth noting that the light mode version is not readable, it's probably something we want to fix before landing:

ljharb · 2021-03-18T03:17:09Z

What’s not readable about the light mode version?

marsonya · 2021-03-18T05:14:19Z

What’s not readable about the light mode version?

The Stability note below the table is not visible in the light version.

Signed-off-by: James M Snell <jasnell@gmail.com>

mhdawson

LGTM

Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: nodejs#25099

Signed-off-by: James M Snell <jasnell@gmail.com>

jasnell · 2021-03-19T19:39:08Z

Landed in 971e009...d3417bb

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: #25099 PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: #25099 PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

@Linkgoron

Notable changes: * buffer: * implement btoa and atob (James M Snell) #37529 * deps: * upgrade npm to 7.7.6 (Ruy Adorno) #37968 * doc: * add legacy status to stability index (James M Snell) #37784 * add @Linkgoron to collaborators (Nitzan Uziely) #37817 * http: * add http.ClientRequest.getRawHeaderNames() (simov) #37660

@Linkgoron

PR-URL: #37977 Notable changes: * buffer: * implement btoa and atob (James M Snell) #37529 * deps: * upgrade npm to 7.7.6 (Ruy Adorno) #37968 * doc: * add legacy status to stability index (James M Snell) #37784 * add @Linkgoron to collaborators (Nitzan Uziely) #37817 * http: * add http.ClientRequest.getRawHeaderNames() (simov) #37660

@Linkgoron

PR-URL: #37977 Notable changes: * buffer: * implement btoa and atob (James M Snell) #37529 * deps: * upgrade npm to 7.7.6 (Ruy Adorno) #37968 * doc: * add legacy status to stability index (James M Snell) #37784 * add @Linkgoron to collaborators (Nitzan Uziely) #37817 * http: * add http.ClientRequest.getRawHeaderNames() (simov) #37660

@Linkgoron

PR-URL: #37977 Notable changes: * buffer: * implement btoa and atob (James M Snell) #37529 * deps: * upgrade npm to 7.7.6 (Ruy Adorno) #37968 * doc: * add legacy status to stability index (James M Snell) #37784 * add @Linkgoron to collaborators (Nitzan Uziely) #37817 * http: * add http.ClientRequest.getRawHeaderNames() (simov) #37660

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: #25099 PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Signed-off-by: James M Snell <jasnell@gmail.com> PR-URL: #37784 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Vladimir de Turckheim <vlad2t@hotmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Beth Griggs <bgriggs@redhat.com>

Notable changes: * assert: * change status of legacy asserts (James M Snell) (#38113) * doc: * apply style for legacy status (James M Snell) (#37784) * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: cherry-pick cf71540c684c (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * fs: * add promisified readFile benchmark (Nitzan Uziely) (#37608) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * lib: * create diagnostics\_channel module (Stephen Belanger) (#34895) * implement AbortSignal.abort() (James M Snell) (#37693) * test: * update dom/abort tests (James M Snell) (#37693) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101)

PR-URL: #38507 Notable changes: * assert: * change status of legacy asserts (James M Snell) (#38113) * doc: * apply style for legacy status (James M Snell) (#37784) * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: cherry-pick cf71540c684c (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * fs: * add promisified readFile benchmark (Nitzan Uziely) (#37608) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * lib: * create diagnostics\_channel module (Stephen Belanger) (#34895) * implement AbortSignal.abort() (James M Snell) (#37693) * test: * update dom/abort tests (James M Snell) (#37693) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101)

PR-URL: #38507 Notable changes: * assert: * change status of legacy asserts (James M Snell) (#38113) * crypto: * implement randomuuid (James M Snell) (#36729) * doc: * apply style for legacy status (James M Snell) (#37784) * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: Backport various patches for Apple Silicon support (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * lib: * create diagnostics\_channel module (Stephen Belanger) (#34895) * implement AbortSignal.abort() (James M Snell) (#37693) * test: * update dom/abort tests (James M Snell) (#37693) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101)

PR-URL: #38507 Notable changes: * crypto: * implement randomuuid (James M Snell) (#36729) * doc: * apply style for legacy status (James M Snell) (#37784) * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: Backport various patches for Apple Silicon support (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * lib: * create diagnostics\_channel module (Stephen Belanger) (#34895) * implement AbortSignal.abort() (James M Snell) (#37693) * test: * update dom/abort tests (James M Snell) (#37693) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101)

Notable changes: Diagnostics channel (experimental module): `diagnostics_channel` is a new experimental module that provides an API to create named channels to report arbitrary message data for diagnostics purposes. The module was initially introduced in Node.js v15.1.0 and is backported to v14.17.0 to enable testing it at a larger scale. With `diagnostics_channel`, Node.js core and module authors can publish contextual data about what they are doing at a given time. This could be the hostname and query string of a mysql query, for example. Just create a named channel with `dc.channel(name)` and call `channel.publish(data)` to send the data to any listeners to that channel. ```js const dc = require('diagnostics_channel'); const channel = dc.channel('mysql.query'); MySQL.prototype.query = function query(queryString, values, callback) { // Broadcast query information whenever a query is made channel.publish({ query: queryString, host: this.hostname, }); this.doQuery(queryString, values, callback); }; ``` Channels are like one big global event emitter but are split into separate objects to ensure they get the best performance. If nothing is listening to the channel, the publishing overhead should be as close to zero as possible. Consuming channel data is as easy as using `channel.subscribe(listener)` to run a function whenever a message is published to that channel. ```js const dc = require('diagnostics_channel'); const channel = dc.channel('mysql.query'); channel.subscribe(({ query, host }) => { console.log(`mysql query to ${host}: ${query}`); }); ``` The data captured can be used to provide context for what an app is doing at a given time. This can be used for things like augmenting tracing data, tracking network and filesystem activity, logging queries, and many other things. It's also a very useful data source for diagnostics tools to provide a clearer picture of exactly what the application is doing at a given point in the data they are presenting. Contributed by Stephen Belanger (#34895). UUID support in the crypto module: The new `crypto.randomUUID()` method now allows to generate random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) Version 4 UUID strings: ```js const { randomUUID } = require('crypto'); console.log(randomUUID()); // 'aa7c91a1-f8fc-4339-b9db-f93fc7233429' ``` Contributed by James M Snell (#36729. Experimental support for `AbortController` and `AbortSignal`: Node.js 14.17.0 adds experimental partial support for `AbortController` and `AbortSignal`. Both constructors can be enabled globally using the `--experimental-abortcontroller` flag. Additionally, several Node.js APIs have been updated to support `AbortSignal` for cancellation. It is not mandatory to use the built-in constructors with them. Any spec-compliant third-party alternatives should be compatible. `AbortSignal` support was added to the following methods: * `child_process.exec` * `child_process.execFile` * `child_process.fork` * `child_process.spawn` * `dgram.createSocket` * `events.on` * `events.once` * `fs.readFile` * `fs.watch` * `fs.writeFile` * `http.request` * `https.request` * `http2Session.request` * The promisified variants of `setImmediate` and `setTimeout` Other notable changes: * doc: * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: Backport various patches for Apple Silicon support (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101) PR-URL: #38507

Notable Changes: Diagnostics channel (experimental module): `diagnostics_channel` is a new experimental module that provides an API to create named channels to report arbitrary message data for diagnostics purposes. The module was initially introduced in Node.js v15.1.0 and is backported to v14.17.0 to enable testing it at a larger scale. With `diagnostics_channel`, Node.js core and module authors can publish contextual data about what they are doing at a given time. This could be the hostname and query string of a mysql query, for example. Just create a named channel with `dc.channel(name)` and call `channel.publish(data)` to send the data to any listeners to that channel. ```js const dc = require('diagnostics_channel'); const channel = dc.channel('mysql.query'); MySQL.prototype.query = function query(queryString, values, callback) { // Broadcast query information whenever a query is made channel.publish({ query: queryString, host: this.hostname, }); this.doQuery(queryString, values, callback); }; ``` Channels are like one big global event emitter but are split into separate objects to ensure they get the best performance. If nothing is listening to the channel, the publishing overhead should be as close to zero as possible. Consuming channel data is as easy as using `channel.subscribe(listener)` to run a function whenever a message is published to that channel. ```js const dc = require('diagnostics_channel'); const channel = dc.channel('mysql.query'); channel.subscribe(({ query, host }) => { console.log(`mysql query to ${host}: ${query}`); }); ``` The data captured can be used to provide context for what an app is doing at a given time. This can be used for things like augmenting tracing data, tracking network and filesystem activity, logging queries, and many other things. It's also a very useful data source for diagnostics tools to provide a clearer picture of exactly what the application is doing at a given point in the data they are presenting. Contributed by Stephen Belanger (#34895). UUID support in the crypto module: The new `crypto.randomUUID()` method now allows to generate random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) Version 4 UUID strings: ```js const { randomUUID } = require('crypto'); console.log(randomUUID()); // 'aa7c91a1-f8fc-4339-b9db-f93fc7233429' ``` Contributed by James M Snell (#36729). Experimental support for `AbortController` and `AbortSignal`: Node.js 14.17.0 adds experimental partial support for `AbortController` and `AbortSignal`. Both constructors can be enabled globally using the `--experimental-abortcontroller` flag. Additionally, several Node.js APIs have been updated to support `AbortSignal` for cancellation. It is not mandatory to use the built-in constructors with them. Any spec-compliant third-party alternatives should be compatible. `AbortSignal` support was added to the following methods: * `child_process.exec` * `child_process.execFile` * `child_process.fork` * `child_process.spawn` * `dgram.createSocket` * `events.on` * `events.once` * `fs.readFile` * `fs.watch` * `fs.writeFile` * `http.request` * `https.request` * `http2Session.request` * The promisified variants of `setImmediate` and `setTimeout` Other notable changes: * doc: * revoke deprecation of legacy url, change status to legacy (James M Snell) (#37784) * add legacy status to stability index (James M Snell) (#37784) * upgrade stability status of report API (Gireesh Punathil) (#35654) * deps: * V8: Backport various patches for Apple Silicon support (BoHong Li) (#38051) * update ICU to 68.1 (Michaël Zasso) (#36187) * upgrade to libuv 1.41.0 (Colin Ihrig) (#37360) * http: * add http.ClientRequest.getRawHeaderNames() (simov) (#37660) * report request start and end with diagnostics\_channel (Stephen Belanger) (#34895) * util: * add getSystemErrorMap() impl (eladkeyshawn) (#38101) PR-URL: #38507

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Mar 17, 2021

jasnell force-pushed the add-legacy-status branch from 56d709d to d8da03f Compare March 17, 2021 19:49

ljharb reviewed Mar 17, 2021

View reviewed changes

doc/api/deprecations.md Outdated Show resolved Hide resolved

addaleax approved these changes Mar 17, 2021

View reviewed changes

mcollina approved these changes Mar 17, 2021

View reviewed changes

vdeturckheim approved these changes Mar 17, 2021

View reviewed changes

aduh95 reviewed Mar 17, 2021

View reviewed changes

doc/api/url.md Outdated Show resolved Hide resolved

doc/api/deprecations.md Outdated Show resolved Hide resolved

jasnell added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Mar 17, 2021

addaleax mentioned this pull request Mar 17, 2021

buffer: expose btoa and atob as globals #37786

Closed

marsonya approved these changes Mar 18, 2021

View reviewed changes

jasnell mentioned this pull request Mar 19, 2021

WhatWG URL provides no suitable replacement for url.format() #25099

Closed

doc: add legacy status to stability index

f4d3377

Signed-off-by: James M Snell <jasnell@gmail.com>

jasnell force-pushed the add-legacy-status branch from 1da2fbe to 3a762c1 Compare March 19, 2021 15:01

targos approved these changes Mar 19, 2021

View reviewed changes

mhdawson reviewed Mar 19, 2021

View reviewed changes

BethGriggs approved these changes Mar 19, 2021

View reviewed changes

doc: revoke deprecation of legacy url, change status to legacy

c22762c

Signed-off-by: James M Snell <jasnell@gmail.com> Fixes: nodejs#25099

jasnell force-pushed the add-legacy-status branch from 3a762c1 to fa508a2 Compare March 19, 2021 17:55

doc: apply style for legacy status

dcc2345

Signed-off-by: James M Snell <jasnell@gmail.com>

jasnell force-pushed the add-legacy-status branch from fa508a2 to dcc2345 Compare March 19, 2021 17:57

jasnell closed this Mar 19, 2021

ruyadorno added the notable-change PRs with changes that should be highlighted in changelogs. label Mar 24, 2021

ruyadorno mentioned this pull request Mar 30, 2021

v15.13.0 proposal #37977

Merged

danielleadams mentioned this pull request May 3, 2021

v14.17.0 proposal #38507

Merged

kt3k mentioned this pull request Nov 8, 2021

docs(node/querystring): Add docs denoland/deno_std#1531

Merged

RaisinTen mentioned this pull request Mar 6, 2022

Are we ready to deprecate url.parse() now? #42232

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add legacy status #37784

doc: add legacy status #37784

jasnell commented Mar 17, 2021

ljharb left a comment

mcollina left a comment

aduh95 commented Mar 17, 2021

ljharb commented Mar 18, 2021

marsonya commented Mar 18, 2021

mhdawson left a comment

jasnell commented Mar 19, 2021

doc: add legacy status #37784

doc: add legacy status #37784

Conversation

jasnell commented Mar 17, 2021

ljharb left a comment

Choose a reason for hiding this comment

mcollina left a comment

Choose a reason for hiding this comment

aduh95 commented Mar 17, 2021

ljharb commented Mar 18, 2021

marsonya commented Mar 18, 2021

mhdawson left a comment

Choose a reason for hiding this comment

jasnell commented Mar 19, 2021