Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[REQUEST]: Document Breaking Changes in 9.0 #16713

Closed
bradennapier opened this issue Nov 3, 2017 · 10 comments
Closed

[REQUEST]: Document Breaking Changes in 9.0 #16713

bradennapier opened this issue Nov 3, 2017 · 10 comments

Comments

@bradennapier
Copy link

  • 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
Copy link
Member

addaleax commented Nov 3, 2017

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

@Trott
Copy link
Member

Trott commented Nov 3, 2017

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
Copy link
Author

bradennapier commented Nov 3, 2017

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
Copy link
Member

joyeecheung commented Nov 3, 2017

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
Copy link
Author

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)

@jasnell
Copy link
Member

jasnell commented Nov 3, 2017

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
Copy link
Author

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

Semver-Major (Breaking)

  • blah blah

Semver-Major

  • blah blah

@jasnell
Copy link
Member

jasnell commented Nov 3, 2017

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
Copy link
Author

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
Copy link
Member

gibfahn commented Nov 3, 2017

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 😁 .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

6 participants