Repository navigation
[REQUEST]: Document Breaking Changes in 9.0 #16713
Description
Activity
Fwiw, there is a list of breaking changes in the changelog for Node 9.
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.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.
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
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) [assert: fix assert.fail with zero arguments #13974](https://git
- [
One thing that I've done for all of the major releases is separate out the
semver-major,semver-minorandsemver-patchcommits into separate lists to at least make those more visible. I'd definitely be +:100+ to changing the headers of each list to something likeBreaking Changes (semver-major)... the only issue with that is that the changes are only Potentially breaking... should we have some way of clarifying that?You could definitely just break it into two semver-major headlines.
Semver-Major (Breaking)
- blah blah
Semver-Major
- blah blah
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? :-)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.
Reacted by James M SnellI think
Breaking Changesas 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 😁 .
Reacted by Rich Trott and Joyee Cheung
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
axiosorfollow-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