Merge pull request #772 from sigstore/pre-ga-docs

update readmes

Author: loosebazooka

README.md

@@ -5,22 +5,28 @@
 # sigstore-java
 A sigstore java client for interacting with sigstore infrastructure
 
-⚠️ This project is not ready for general-purpose use! ⚠️
+## Requirements
+* Java 11 (https://github.com/sigstore/sigstore-java requires Java 11)
+This project requires a minimum of Java 11
 
-This project requires a minimum of Java 11 and is current in pre-release,
-apis and dependencies are likely to change
-
-You can files issues directly on this project or if you have any questions
-message us on the [sigstore#java](https://sigstore.slack.com/archives/C03239XUL92) slack channel
+You can file [issues directly](https://github.com/sigstore/sigstore-java/issues) on this project or
+if you have any questions message us on the [sigstore#java](https://sigstore.slack.com/archives/C03239XUL92)
+slack channel
 
 ## Usage
 
+### Build plugins
+
+For use directly with your java build. See [maven](https://github.com/sigstore/sigstore-java/tree/main/sigstore-maven-plugin) or [gradle](https://github.com/sigstore/sigstore-java/tree/main/sigstore-gradle)
+build plugin specifics.
+
 ### Keyless Signing And Verification
 
 #### Signing
 ```java
 Path testArtifact = Paths.get("path/to/my/file.jar")
 
+// sign using the sigstore public instance
 var signer = KeylessSigner.builder().sigstorePublicDefaults().build();
 Bundle result = signer.signFile(testArtifact);
 
@@ -30,29 +36,29 @@ String bundleJson = result.toJson();
 
 #### Verification
 
-##### Read bundle
+##### Get artifact and bundle
 ```java
-Path bundleFile = // java.nio.Path to a .sigstore.json signature bundle file
-Bundle bundle = Bundle.from(Files.newBufferedReader(bundleFile, StandardCharsets.UTF_8));
+Path artifact = Paths.get("path/to/my-artifact");
+
+// import a json formatted sigstore bundle
+Path bundleFile = Paths.get("path/to/my-artifact.sigstore.json");
+Bundle bundle = Bundle.from(bundleFile, StandardCharsets.UTF_8);
 ```
 
 ##### Configure verification options
 ```java
 // add certificate policy to verify the identity of the signer
-VerificationOptions verificationOptions =
-    VerificationOptions.builder()
-        .addCertificateIdentities(
-            CertificateIdentity.builder()
-                .issuer("https://accounts.example.com"))
-                .subjectAlternativeName("[email protected]")
-                .build())
-        .build();
+VerificationOptions options = VerificationOptions.builder().addCertificateMatchers(
+  CertificateMatcher.fulcio()
+    .subjectAlternativeName(StringMatcher.string("[email protected]"))
+    .issuer(StringMatcher.string("https://accounts.example.com"))
+    .build());
 ```
 
 ##### Do verification
 ```java
-Path artifact = // java.nio.Path to artifact file
 try {
+  // verify using the sigstore public instance
   var verifier = new KeylessVerifier.builder().sigstorePublicDefaults().build();
   verifier.verify(artifact, bundle, verificationOptions);
   // verification passed!
@@ -67,7 +73,7 @@ The public stable API is limited to `dev.sigstore.KeylessSigner`(https://javadoc
 
 You can browse Javadoc at https://javadoc.io/doc/dev.sigstore/sigstore-java.
 
-To build javadoc from the sources, use the following command:
+To build and view javadoc from the sources, use the following command:
 
 ```sh
 $ ./gradlew javadoc

sigstore-gradle/README.md

@@ -1,8 +1,9 @@
-## sigstore-gradle
+[![Gradle Plugin Portal](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/dev/sigstore/sigstore-gradle-sign-plugin/maven-metadata.xml.svg?color&label=gradle%20plugin%20portal)](https://plugins.gradle.org/plugin/dev.sigstore.sign/)
+
+# sigstore-gradle
 
 A Gradle plugin for signing artifacts with Sigstore.
 
-`dev.sigstore.sign` is available on the gradle plugin portal.
 Signature format uses [Sigstore bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) JSON as the output format.
 
 ## Requirements
@@ -18,11 +19,14 @@ plugins {
     id("dev.sigstore.sign")
 }
 
-// It would automatically sign all Maven publications
-// By default, it would use GitHub Actions OIDC when available,
-// and it would resort to Web Browser OIDC otherwise.
+// Automatically sign all Maven publications, using GitHub Actions OIDC when available,
+// and browser based OIDC otherwise.
 ```
 
+### Outputs
+
+For each file to be published an associated `<filename>.sigstore.json` signature file will be generated
+
 ### GitHub Actions OIDC support
 
 In order for the required environment variables to be available, the workflow requires the following permissions:
@@ -35,6 +39,7 @@ permissions:
 
 See [GitHub documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers#adding-permissions-settings) for details.
 
+
 ## Full configuration
 
 ```kotlin

sigstore-maven-plugin/README.md

@@ -1,9 +1,10 @@
-# sigstore-maven-plugin
+[![Maven Central](https://img.shields.io/maven-central/v/dev.sigstore/sigstore-maven-plugin.svg?color&label=maven%20central)](https://central.sonatype.com/artifact/dev.sigstore/sigstore-maven-plugin)
 
-[![Maven Central](https://img.shields.io/maven-central/v/dev.sigstore/sigstore-maven-plugin.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/dev.sigstore/sigstore-maven-plugin)
+# sigstore-maven-plugin
 
 A Maven plugin for signing artifacts with Sigstore
 
+Signature format uses [Sigstore bundle](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto) JSON as the output format.
 
 ## Requirements
 
@@ -27,6 +28,10 @@ A Maven plugin for signing artifacts with Sigstore
       </plugin>
 ```
 
+### Outputs
+
+For each file to be published an associated `<filename>.sigstore.json` signature file will be generated
+
 ### GitHub Actions OIDC support
 
 In order for the required environment variables to be available, the workflow requires the following permissions: