doc: improvements to crypto.markdown copy #5230

estliberitas · 2016-02-15T00:41:26Z

Fix several typos. Add missing links.

estliberitas · 2016-02-15T00:52:38Z

Also, guys. While I've been working on this I've got a question about crypto.Certificate. Why is it not a static class or just an object with functions?
I could not find any reason for using crypto.Certificate as a class, because:

crypto.Certificate just wraps C++ Certificate class
C++ Certificate methods do not work with instance, just extract environment from it (one method only - Certificate::VerifySpkac())

So I guess there should be a reason for this. Like inheriting of AsyncWrap or MakeWeak makes sense with memory or handle management or so.

jasnell · 2016-02-15T15:45:10Z

LGTM

Knighton910 · 2016-02-19T17:31:05Z

LGTM

jasnell · 2016-02-19T18:55:27Z

LGTM

estliberitas · 2016-02-19T20:07:46Z

Guys, can anyone answer question above? Or should I create separate issue for this q?

Knighton910 · 2016-02-19T20:48:13Z

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 crypto label on it.

jasnell · 2016-02-19T23:39:02Z

Not sure of the history on that class, it's likely just some left over legacy thing. Perhaps @indutny or @shigeki could shed some light on it.

jasnell · 2016-02-19T23:39:19Z

@nodejs/crypto

bnoordhuis · 2016-02-20T11:36:41Z

Why is it not a static class or just an object with functions?

No reason except that it follows how other types are implemented.

estliberitas · 2016-02-20T13:17:04Z

@bnoordhuis Would it be a good idea to simplify things and, for example, put Certificate instance methods in crypto module? Or this is a case when beauty of consistency is preferred?

bnoordhuis · 2016-02-20T16:11:19Z

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.

bnoordhuis · 2016-02-20T16:12:34Z

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.

estliberitas · 2016-02-20T16:23:46Z

@bnoordhuis if it would be a change for the good of everyone, I'd like to implement it and let others judge it.

bnoordhuis · 2016-02-20T16:29:15Z

Go ahead, I'll review it. Please make sure you read CONTRIBUTING.md first and that make test passes before you open the pull request. Cheers.

jasnell · 2016-02-20T16:31:16Z

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.

ChALkeR · 2016-02-21T08:25:46Z

@estliberitas Can you split the actual (non-doc) change proposal into a separate issue, please?

@jasnell This is everything that I found for crypto.*\.Certificate (downloads/month on the left):

14264   diff-dom-2.0.0.tgz/venv/src/node-v4.1.1/test/parallel/test-crypto-certificate.js:21:var certificate = new crypto.Certificate();
483     webid-0.3.7.tgz/tls/index.js:12:var certificate = new crypto.Certificate()
483     webid-0.3.7.tgz/test/test.js:8:var certificate = new crypto.Certificate()
434     pn-1.0.0.tgz/crypto.js:5:  Certificate: { enumerable: true, value: crypto.Certificate },
60      biojs-vis-blast-0.1.5.tgz/node/test/simple/test-crypto-certificate.js:37:var certificate = new crypto.Certificate();
43      flush-all-0.1.1.tgz/node-v0.13/test/simple/test-crypto-certificate.js:37:var certificate = new crypto.Certificate();
38      node-core-test-simple-0.11.11.tgz/test-crypto-certificate.js:37:var certificate = new crypto.Certificate();

The first line actually looks as a diff-dom packaging error to me, I'm going to report that now.

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.

estliberitas · 2016-02-21T13:49:54Z

Cool, okay, I'll be working on it today.

jasnell · 2016-02-21T19:10:02Z

@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!

estliberitas · 2016-02-21T19:33:11Z

@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:

Wrap existing API in internal/util.deprecate() and introduce another API.
Remove old API.

Correct?

johanneswilm · 2016-02-21T20:01:07Z

The first line actually looks as a diff-dom packaging error to me, I'm going to report that now.

Indeed. Should be fixed in version 2.0.1

bnoordhuis · 2016-02-21T20:05:10Z

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.

estliberitas · 2016-02-21T20:10:59Z

@bnoordhuis

Then again, maybe not. Implementing it as static methods would eliminate the need for a persistent handle and that's never a bad thing.

So this is about binding implementation?

bnoordhuis · 2016-02-21T20:44:53Z

Correct.

ChALkeR · 2016-02-21T21:33:11Z

@jasnell

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.

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 npm greps are not the absolute source of information — someone could be using this in their private code (e.g. their website apps etc). Also, there could be false negatives even in the data that I have.

We should take into account that crypto module is labeled Stable in the docs.

estliberitas · 2016-02-23T09:31:15Z

@bnoordhuis

Correct.

Would it be semver-(minor|major)? I guess, no, thus no new public API is added and existing is not changed.

bnoordhuis · 2016-02-23T11:10:32Z

It could be semver-patch but because it's not a real bug fix, I'd be conservative and label it semver-minor.

silverwind · 2016-02-27T16:44:15Z

doc/api/crypto.markdown

@@ -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].


where does this writable-write link to?

Oh, found it. maybe name it stream-writable-write for clarity?

@silverwind done

silverwind · 2016-02-27T16:47:17Z

LGTM except suggestion above.

silverwind · 2016-02-28T01:46:48Z

@estliberitas still not applying cleanly here:

Error: git am exited with code: 128
.git/rebase-apply/patch:590: trailing whitespace.
[`ecdh.setPrivateKey()`]: #crypto_ecdh_setprivatekey_private_key_encoding
.git/rebase-apply/patch:596: trailing whitespace.
[`hmac.digest()`]: #crypto_hmac_digest_encoding
error: patch failed: doc/api/crypto.markdown:899
error: doc/api/crypto.markdown: patch does not apply

Fix several typos. Add missing links.

estliberitas · 2016-02-28T19:32:34Z

@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]>

silverwind · 2016-02-28T20:21:54Z

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]>

mscdex added crypto Issues and PRs related to the crypto subsystem. doc Issues and PRs related to the documentations. labels Feb 15, 2016

jasnell added the lts-watch-v4.x label Feb 15, 2016

estliberitas mentioned this pull request Feb 19, 2016

doc: markdown links do not turn into real links #5322

Closed

ChALkeR mentioned this pull request Feb 21, 2016

Do not package the venv dir (reduce the installed size 200x) fiduswriter/diffDOM#35

Closed

estliberitas mentioned this pull request Feb 23, 2016

crypto: simplify Certificate class bindings #5382

Closed

4 tasks

silverwind reviewed Feb 27, 2016
View reviewed changes

doc: improvements to crypto.markdown copy

8999292

Fix several typos. Add missing links.

silverwind closed this Feb 28, 2016

estliberitas deleted the doc-fix-crypto branch February 28, 2016 21:13

Fishrock123 mentioned this pull request Mar 1, 2016

Release proposal: v5.7.1 #5464

Merged

5 tasks

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Mar 1, 2016

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: improvements to crypto.markdown copy #5230

doc: improvements to crypto.markdown copy #5230

estliberitas commented Feb 15, 2016

estliberitas commented Feb 15, 2016

jasnell commented Feb 15, 2016

Knighton910 commented Feb 19, 2016

jasnell commented Feb 19, 2016

estliberitas commented Feb 19, 2016

Knighton910 commented Feb 19, 2016

jasnell commented Feb 19, 2016

jasnell commented Feb 19, 2016

bnoordhuis commented Feb 20, 2016

estliberitas commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

estliberitas commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

jasnell commented Feb 20, 2016

ChALkeR commented Feb 21, 2016

estliberitas commented Feb 21, 2016

jasnell commented Feb 21, 2016

estliberitas commented Feb 21, 2016

johanneswilm commented Feb 21, 2016

bnoordhuis commented Feb 21, 2016

estliberitas commented Feb 21, 2016

bnoordhuis commented Feb 21, 2016

ChALkeR commented Feb 21, 2016

estliberitas commented Feb 23, 2016

bnoordhuis commented Feb 23, 2016

silverwind Feb 27, 2016

silverwind Feb 27, 2016

estliberitas Feb 27, 2016

silverwind commented Feb 27, 2016

silverwind commented Feb 28, 2016

estliberitas commented Feb 28, 2016

silverwind commented Feb 28, 2016

doc: improvements to crypto.markdown copy #5230

doc: improvements to crypto.markdown copy #5230

Conversation

estliberitas commented Feb 15, 2016

estliberitas commented Feb 15, 2016

jasnell commented Feb 15, 2016

Knighton910 commented Feb 19, 2016

jasnell commented Feb 19, 2016

estliberitas commented Feb 19, 2016

Knighton910 commented Feb 19, 2016

jasnell commented Feb 19, 2016

jasnell commented Feb 19, 2016

bnoordhuis commented Feb 20, 2016

estliberitas commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

estliberitas commented Feb 20, 2016

bnoordhuis commented Feb 20, 2016

jasnell commented Feb 20, 2016

ChALkeR commented Feb 21, 2016

estliberitas commented Feb 21, 2016

jasnell commented Feb 21, 2016

estliberitas commented Feb 21, 2016

johanneswilm commented Feb 21, 2016

bnoordhuis commented Feb 21, 2016

estliberitas commented Feb 21, 2016

bnoordhuis commented Feb 21, 2016

ChALkeR commented Feb 21, 2016

estliberitas commented Feb 23, 2016

bnoordhuis commented Feb 23, 2016

silverwind Feb 27, 2016

Choose a reason for hiding this comment

silverwind Feb 27, 2016

Choose a reason for hiding this comment

estliberitas Feb 27, 2016

Choose a reason for hiding this comment

silverwind commented Feb 27, 2016

silverwind commented Feb 28, 2016

estliberitas commented Feb 28, 2016

silverwind commented Feb 28, 2016