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

doc, punycode: soft-deprecation of the punycode module #7941

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion doc/api/punycode.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
# punycode

Stability: 2 - Stable
Stability: 0 - Deprecated

**The version of the punycode module bundled in Node.js is being deprecated**.
In a future major version of Node.js this module will be removed. Users
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we use more specific version number instead of the word "future"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, let’s be specific. I’ll then update the Punycode.js README accordingly.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how specific we can be... Generally we've tried not to commit
to specific versions. It would be at least v8 before we could do the hard
deprecation.

On Monday, August 1, 2016, Mathias Bynens notifications@github.com wrote:

In doc/api/punycode.md
#7941 (comment):

@@ -1,6 +1,11 @@

punycode

  • Stability: 2 - Stable
  • Stability: 0 - Deprecated

+The version of the punycode module bundled in Node.js is being deprecated.
+In a future major version of Node.js this module will be removed. Users

Yeah, let’s be specific. I’ll then update the Punycode.js README
accordingly.


You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
https://github.com/nodejs/node/pull/7941/files/a1ee6dac91984047af0f6167031e6716bf6c8648#r73102561,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAa2ecTY2uR6HajrntHHGZHazWU51Yn7ks5qbunWgaJpZM4JZ4pZ
.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jsnell as we have added this pull-request to the 7.0.0 milestone, so could we just simply make it be deprecated entirely at v8 as we will notify user at v7.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hard deprecations are a bit touchy, since it means potentially breaking users' code. It is possible that some new data comes up between v7.x and v8.x versions that would make the CTC consider a hard deprecation later than v8.x releases.

If mentioning a specific version is considered to be a good incentive for users to move to using the npm module, then I agree we should do that. Otherwise, it seems like it would not be that useful for users, and it would actually limit our options.

So my question is: what are we trying to achieve by mentioning a specific version?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mathiasbynens ... the best bet for your users would be to begin recommending transitioning off the bundled version to the installable version starting in v7, even tho it's just a "soft deprecation". Ideally those users would be migrated already long before we do the hard deprecation (where warnings and errors start being reported). In fact, the faster users transition off the bundled version, the faster we'll be able to do that hard deprecation.

currently depending on the `punycode` module should switch to using the
userland-provided [Punycode.js][] module instead.

The `punycode` module is a bundled version of the [Punycode.js][] module. It
can be accessed using:
Expand Down