-
Notifications
You must be signed in to change notification settings - Fork 29.6k
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: improvements to crypto.markdown copy #5230
Conversation
Also, guys. While I've been working on this I've got a question about
So I guess there should be a reason for this. Like inheriting of |
LGTM |
LGTM |
1 similar comment
LGTM |
Guys, can anyone answer question above? Or should I create separate issue for this q? |
Personally, I'd open a separate Issue for it. That way someone will get to it faster & I'd cc some of the guys who worked on the crypto doc. But someone should get to it here, as well. This issue does have a |
@nodejs/crypto |
No reason except that it follows how other types are implemented. |
@bnoordhuis Would it be a good idea to simplify things and, for example, put |
If it was new code, I would have pushed to implement it as static methods. But it's existing, working code; it would basically be an aesthetic change. |
Then again, maybe not. Implementing it as static methods would eliminate the need for a persistent handle and that's never a bad thing. |
@bnoordhuis if it would be a change for the good of everyone, I'd like to implement it and let others judge it. |
Go ahead, I'll review it. Please make sure you read CONTRIBUTING.md first and that |
We should first attempt to see how extensively the current API is used (cc @ChALkeR). The current API form would need to be deprecated. Seems like a good change to make. |
@estliberitas Can you split the actual (non-doc) change proposal into a separate issue, please? @jasnell This is everything that I found for
The first line actually looks as a Even given the false negatives, the usage looks very low, so I think that the change is possible here. It would still require several major releases, of course. |
Cool, okay, I'll be working on it today. |
@ChALkeR +1 thank you for that. So yeah @estliberitas, The existing API would need to go through a deprecation cycle (do a quick search for "deprecated" in the source to see how that's handled in code). The documentation would also need to be updated to show that. Deprecations are a semver-major change so it would hit as part of v6. You can introduce the revamped API alongside the deprecation but the existing stuff cannot be removed until at least v7 or v8. If you need any help, let one of us know! |
@jasnell Okay, I want to walk the whole way to the new API even if it will be released with v8 or so. I'll check soon how deprecations were handled previously. I guess, it is to be a series of 2 PRs:
Correct? |
Indeed. Should be fixed in version 2.0.1 |
Maybe I didn't make myself clear but I wouldn't change the public API, just the implementation details so the persistent handle is no longer necessary. |
So this is about binding implementation? |
Correct. |
I'd go with a documentation-only deprecation in v6, actual deprecation in v7 (perhaps), and possible removal at some point after that (in v8 or later). These We should take into account that |
Would it be |
It could be semver-patch but because it's not a real bug fix, I'd be conservative and label it semver-minor. |
@@ -716,7 +717,7 @@ console.log(sign.sign(private_key, 'hex')); | |||
### sign.sign(private_key[, output_format]) | |||
|
|||
Calculates the signature on all the data passed through using either | |||
`sign.update()` or `sign.write()`. | |||
[`sign.update()`][] or [`sign.write()`][writable-write]. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
where does this writable-write
link to?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh, found it. maybe name it stream-writable-write
for clarity?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@silverwind done
LGTM except suggestion above. |
@estliberitas still not applying cleanly here:
|
Fix several typos. Add missing links.
@silverwind Done. |
Fix several typos. Add missing links. PR-URL: #5230 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Thanks! Landed in f0c0614. |
Fix several typos. Add missing links. PR-URL: #5230 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Fix several typos. Add missing links. PR-URL: #5230 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Fix several typos. Add missing links. PR-URL: #5230 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Fix several typos. Add missing links. PR-URL: #5230 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Kelvin Knighton <[email protected]> Reviewed-By: Roman Reiss <[email protected]>
Fix several typos. Add missing links.