Node: [REQUEST]: Document Breaking Changes in 9.0

[bradennapier]

• Version: 9.0
• Platform: OSX

It would appear that this version implements breaking changes into the http module. I am not really sure where it specifically is being brought up from but it woudl appear from axios or follow-redirects.

Either way, from the minimal documentation on the error it would appear that this is likely due to no longer accepting (undefined) and only allowing () somewhere?

No clue

TypeError [ERR_MISSING_ARGS]: The "value" argument must be specified
0|developm |     at validateHeader (_http_outgoing.js:501:11)
0|developm |     at ClientRequest.setHeader (_http_outgoing.js:510:3)
0|developm |     at new ClientRequest (_http_client.js:173:14)
0|developm |     at Object.request (https.js:241:10)

[addaleax]

Fwiw, there is a list of breaking changes in the changelog for Node 9.

[Trott]

Suggestion: "semver-major" is jargon that should be replaced with "breaking changes" in the changelog.

This would seem to be a common practice and something that is widely understood.

Searching for "semver-major" "changelog" on Google gives less than 600 hits. Searching for "breaking changes" "changelog" results in over 47K hits.

[bradennapier]

Yeah I definitely did not know that is what that meant at all. I knew semver-major meant that, but I didn't put it together that I would look for breaking changes there when I was scanning the docs.

[joyeecheung]

We can have a glossary like the one chromium has.

EDIT: still not everyone will look it up so yeah should probably name them breaking changes in the changelog or add a note

[bradennapier]

It just has to be under releases here. You can keep semver-major or w/e but just headline it at the top / separate them so it ends up like:

Semver-Major (Breaking Changes)

• [de4a749788] - (SEMVER-MAJOR) internal/util: use internal/errors.js (Sebastian Van Sande) #11301
• [db2e093e05] - (SEMVER-MAJOR) assert: handle enumerable symbol keys (Ruben Bridgewater) #15169
• [b0d3bec95c] - (SEMVER-MAJOR) assert: use Same-value equality in deepStrictEqual (Ruben Bridgewater) #15398
• [e13d1df89b] - (SEMVER-MAJOR) assert: support custom errors (geek) #15304
• [ea2e6363f2] - (SEMVER-MAJOR) assert: use SameValueZero in deepStrictEqual (Ruben Bridgewater) #15036
• [c53db1e8e9] - (SEMVER-MAJOR) assert: show thrown message in doesNotThrow() (Ruslan Bekenev) #12167
• [fc463639fa] - (SEMVER-MAJOR) assert: fix assert.fail with zero arguments (Ruben Bridgewater) [#13974](https://git

[jasnell]

One thing that I've done for all of the major releases is separate out the semver-major, semver-minor and semver-patch commits into separate lists to at least make those more visible. I'd definitely be +:100+ to changing the headers of each list to something like Breaking Changes (semver-major) ... the only issue with that is that the changes are only Potentially breaking... should we have some way of clarifying that?

[bradennapier]

You could definitely just break it into two semver-major headlines.

Semver-Major (Breaking)

• blah blah

Semver-Major

• blah blah

[jasnell]

The issue primarily is that what is breaking for some might not be breaking for others, and unfortunately we don't know which is which. Perhaps Semver-Major (Potentially Breaking) would be good enough? :-)

[bradennapier]

Yeah I think as long as it were annotated in any capacity somewhere it will be more than enough. I honestly ignore most of those and read just the top headlines usually (and im sure that is the common case for people) - unless there is something specific I care about (like the HTTP/2 ones in the latest releases).

However, if I saw Breaking anywhere as I scan through it I would definitely spend the time to read those in-depth.

Might be good for any that are "Likely Breaking" or have a bigger impact on previous code to list them at the top as well in. Maybe like the top 3 or something if it sin't a huge task to understand which may be the biggest issue.

Appreciate all your comments on this.

[gibfahn]

I think Breaking Changes as commonly used in Changelogs really means "possibly breaking changes", or "this might break you, you should check", so I'd be good with just doing Semver Major (Breaking Changes), seems like it'll help people, and I don't _think_ we'll get many people complaining that they weren't broken by the changes.

If a change ever broke everyone I don't think we'd ship it 😁 .