Skip to content

Conversation

daniel-sanche
Copy link
Member

implements changes suggested in b/113025362 and b/113025156

@daniel-sanche daniel-sanche added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Sep 21, 2018
@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label Sep 21, 2018
@daniel-sanche daniel-sanche added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Sep 21, 2018
@kokoro-team kokoro-team removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Sep 21, 2018
@daniel-sanche daniel-sanche force-pushed the kms-changes branch 2 times, most recently from 8ede13b to 61c96de Compare September 21, 2018 22:43
@daniel-sanche daniel-sanche removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Sep 24, 2018
@daniel-sanche daniel-sanche added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Sep 28, 2018
@daniel-sanche daniel-sanche added kokoro:force-run Add this label to force Kokoro to re-run the tests. and removed do not merge Indicates a pull request not ready for merge, due to either quality or timing. labels Sep 28, 2018
@kokoro-team kokoro-team removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Sep 28, 2018
@@ -16,6 +16,7 @@

package com.example;

// [START kms_get_asymmetric_public]
Copy link
Contributor

Choose a reason for hiding this comment

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

I don't think you should add the imports for the entire file. Several of these imports aren't even being used in the snippet that is requesting them.

One suggesting for handling this problem is the approach that's being used in #1232. This puts each snippet in it's own file, and the region tags include the imports.

Another suggestion is to add a comment detailing that the PemReader import is needed, and maybe even specify the mvn package name for the user to more easily add it to their pom.

Copy link
Member Author

Choose a reason for hiding this comment

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

We had a discussion about the best way to present these imports in b/113025156, and we decided the universal import region tag would be sufficient. Is it more standard to include imports in each region tag? I could do it that way, but it would require a pretty big refactor, and new PRs for the other languages

(btw, I changed the region tag here - these should be imports for all asymmetric samples, not just get_asymmetric_public)

Copy link
Contributor

Choose a reason for hiding this comment

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

Up until now the standard has been to not include imports in region tags. If we switch the new format, each snippet will be in it's own file so that only relevant imports will be shown.

What page will this be on? I don't think lumping all the imports into one region tag is a good solution for multiple different snippets - it won't be clear which imports go to which snippet.

Copy link
Member Author

Choose a reason for hiding this comment

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

It would have to be on the encrypting and signing docs pages. I think I'll spend some time tomorrow moving imports into each snippet, if that's more in line with existing ones

Copy link
Contributor

Choose a reason for hiding this comment

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

The other suggestion (if you want to avoid a large refactor until the new format is decided upon) would be to update the comment for the functions using the 3rd party library with just that import.

For example add something like this snippet uses BouncyCastleProvider, which can be imported at org.bouncycastle.jce.provider.BouncyCastleProvider to the function comment. This way the third party import would be visible and still only listed for the relevant functions.

@daniel-sanche
Copy link
Member Author

@kurtisvg I did some experimenting, and ended up ended up deciding it looks best with the comments. I think I'll remove the import region tags and go with this for the other languages

@daniel-sanche daniel-sanche merged commit 24d202f into GoogleCloudPlatform:master Oct 18, 2018
@daniel-sanche daniel-sanche deleted the kms-changes branch October 18, 2018 17:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cla: yes This human has signed the Contributor License Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants