doc: Deprecate old debug protocol

[hybrist]

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

As discussed in #10276, we'd want to add a soft deprecation of the --debug flag to the docs.

This just adds the deprecation to the "advanced usage" section, not to the overall page. I think we can actually keep supporting node debug <filename> since it doesn't leak the protocol used (as pid and url do, both of which could have been started with a different version of node).

[Trott]

I wonder if we should remove the "experimental feature" note, especially if we're pointing people to it as an alternative to the deprecated debugger. That doesn't have to happen in this PR (although it could if there's consensus that it should happen).

[hybrist]

Yeah, I was thinking about what the "least worst" option would be. It seemed also bad to remove the doc warning while the runtime still writes one ("docs say go ahead but then the runtime punishes the user with scary warnings").

P.S.: The solution could be to remove the warning in this PR, but there's #8978 already touching those parts.

[Trott]

@nodejs/ctc This is something we should probably decide on sooner rather than later. We may need to create an exception to our deprecation policy for the debugger situation. We may not have much of a choice (unless we want to not upgrade V8 for 18 months).

[addaleax]

nit: Can you wrap this at 80 characters? You should be able to use multiple >s to continue the blockquote, the documentation generator should be able to handle that

[hybrist]

I had it on multiple lines at first but line breaks inside of > were preserved which looked awkward in the rendered version.

[thefourtheye]

@jkrems It's fixed in #11074

[hybrist]

Rebased, only conflict was the changed link at the very bottom.

[mhdawson]

LGTM

[Trott]

Are there semver implications for a docs-only deprecation? I'd like to land this sooner rather than later...

[jasnell]

All deprecations are semver major, including docs only

…

On Tue, Jan 3, 2017 at 7:31 PM Rich Trott ***@***.***> wrote: Are there semver implications for a docs-only deprecation? I'd like to land this sooner rather than later... — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#10320 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAa2eZc3Jctp9F3uWMdU-bW95ZsLsqdUks5rOxJ_gaJpZM4LP9Kh> .

[Trott]

All deprecations are semver major, including docs only

Can we and should we make an exception for this one? If I'm not mistaken, we expect the debugger to be not-working come Node.js 8, so a docs-only deprecation now would seem to be the kind thing to do for our users as opposed to having it go away with no warning.

[Fishrock123]

All deprecations are semver major, including docs only

heh, it's not like we've approved deprecations in-major before when we had no other choice (smalloc)

[jasnell]

I'd rather not start getting into the habit of making exceptions for deprecations. If we want to treat docs only deprecations as anything less than semver-major, then we should establish that as policy and do all docs only deprecations as less than semver-major.

[targos]

Correct me if I'm wrong, but I think that for this case, we must make an exception to our policy. We have to choose between:

• a semver-minor docs only deprecation in 7.x, followed by the removal of the feature in 8.0
• direct removal in 8.0 without deprecation

[Trott]

Consensus at CTC meeting today was that this can move forward.

(This and another issue highlighted how we need to more concretely document our semver policy and @jasnell is restarting an earlier effort to do that.)

Removing ctc-agenda label. Adding labels for hopefully landing this on v6 as well so that people who only use LTS versions have a chance of noticing the doc note.

[Trott]

Landed in 59a61a2.

@jkrems Do we need to runtime deprecate the debug protocol too? Or are we thinking that there's a chance it can be an alias for inspect without too much fallout? Or another option? /cc @Fishrock123

[hybrist]

@Trott The runtime deprecation was already kicked off by @joshgav here: #10276. But yes, warning at runtime (at least in 7.x, maybe/hopefully even in 6.x) would be super useful I think.

[Trott]

Do we need to deprecate vm.runInDebugContext() too? Or is that likely to continue working?

[targos]

I'm not sure. It's using the v8::Debug C++ API.
/cc @hashseed

[hashseed]

vm.runInDebugContext uses the debug context. That is mostly unrelated to the legacy JSON protocol (which will be removed by V8 5.8). We will deprecate debug cont wi the API to access the debug context will be marked accordingly in include/v8.h, but not in the short term.

[evanlucas]

This doesn't land cleanly on v7.x. Someone want to backport?

[hybrist]

@evanlucas Backport = cherry-pick commit against 7.x, resolve conflicts, PR against 7.x branch? If so I could give it a shot.

[evanlucas]

Yes, but Pr against v7.x-staging instead of v7.x

Thanks!

[hybrist]

Resolved here: #11172

[hybrist]

The backport PR has been updated again. I really think we should get this into the published docs rather sooner than later, given how close we are to adding runtime deprecations (or even dropping support).