chore: update common templates (#15)

.kokoro/build.sh

@@ -44,13 +44,26 @@ test)
     bash .kokoro/coerce_logs.sh
     ;;
 lint)
-    mvn com.coveo:fmt-maven-plugin:check
+    mvn \
+      -Penable-samples \
+      com.coveo:fmt-maven-plugin:check
     ;;
 javadoc)
     mvn javadoc:javadoc javadoc:test-javadoc
     ;;
 integration)
     mvn -B ${INTEGRATION_TEST_ARGS} \
+      -Penable-integration-tests \
+      -DtrimStackTrace=false \
+      -Dclirr.skip=true \
+      -Denforcer.skip=true \
+      -fae \
+      verify
+    bash .kokoro/coerce_logs.sh
+    ;;
+samples)
+    mvn -B \
+      -Penable-samples \
       -DtrimStackTrace=false \
       -Dclirr.skip=true \
       -Denforcer.skip=true \

.kokoro/continuous/samples.cfg

@@ -0,0 +1,31 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+  key: "TRAMPOLINE_IMAGE"
+  value: "gcr.io/cloud-devrel-kokoro-resources/java8"
+}
+
+env_vars: {
+  key: "JOB_TYPE"
+  value: "samples"
+}
+
+env_vars: {
+    key: "GCLOUD_PROJECT"
+    value: "gcloud-devel"
+}
+
+env_vars: {
+    key: "GOOGLE_APPLICATION_CREDENTIALS"
+    value: "keystore/73713_java_it_service_account"
+}
+
+before_action {
+  fetch_keystore {
+    keystore_resource {
+      keystore_config_id: 73713
+      keyname: "java_it_service_account"
+    }
+  }
+}

.kokoro/nightly/samples.cfg

@@ -0,0 +1,31 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+    key: "TRAMPOLINE_IMAGE"
+    value: "gcr.io/cloud-devrel-kokoro-resources/java8"
+}
+
+env_vars: {
+    key: "JOB_TYPE"
+    value: "samples"
+}
+
+env_vars: {
+    key: "GCLOUD_PROJECT"
+    value: "gcloud-devel"
+}
+
+env_vars: {
+    key: "GOOGLE_APPLICATION_CREDENTIALS"
+    value: "keystore/73713_java_it_service_account"
+}
+
+before_action {
+  fetch_keystore {
+    keystore_resource {
+      keystore_config_id: 73713
+      keyname: "java_it_service_account"
+    }
+  }
+}

.kokoro/presubmit/samples.cfg

@@ -0,0 +1,31 @@
+# Format: //devtools/kokoro/config/proto/build.proto
+
+# Configure the docker image for kokoro-trampoline.
+env_vars: {
+  key: "TRAMPOLINE_IMAGE"
+  value: "gcr.io/cloud-devrel-kokoro-resources/java8"
+}
+
+env_vars: {
+  key: "JOB_TYPE"
+  value: "samples"
+}
+
+env_vars: {
+    key: "GCLOUD_PROJECT"
+    value: "gcloud-devel"
+}
+
+env_vars: {
+    key: "GOOGLE_APPLICATION_CREDENTIALS"
+    value: "keystore/73713_java_it_service_account"
+}
+
+before_action {
+  fetch_keystore {
+    keystore_resource {
+      keystore_config_id: 73713
+      keyname: "java_it_service_account"
+    }
+  }
+}

CONTRIBUTING.md

@@ -25,4 +25,106 @@ information on using pull requests.
 ## Community Guidelines
 
 This project follows
-[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/).
+
+## Building the project
+
+To build, package, and run all unit tests run the command
+
+```
+mvn clean verify
+```
+
+### Running Integration tests
+
+To include integration tests when building the project, you need access to
+a GCP Project with a valid service account. 
+
+For instructions on how to generate a service account and corresponding
+credentials JSON see: [Creating a Service Account][1].
+
+Then run the following to build, package, run all unit tests and run all
+integration tests.
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account.json
+mvn -Penable-integration-tests clean verify
+```
+
+## Code Samples
+
+Code Samples must be bundled in separate Maven modules, and guarded by a
+Maven profile with the name `enable-samples`.
+
+The samples must be separate from the primary project for a few reasons:
+1. Primary projects have a minimum Java version of Java 7 whereas samples have
+   a minimum Java version of Java 8. Due to this we need the ability to
+   selectively exclude samples from a build run.
+2. Many code samples depend on external GCP services and need
+   credentials to access the service.
+3. Code samples are not released as Maven artifacts and must be excluded from 
+   release builds.
+
+### Building
+
+```bash
+mvn -Penable-samples clean verify
+```
+
+Some samples require access to GCP services and require a service account:
+
+```bash
+export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account.json
+mvn -Penable-samples clean verify
+```
+
+### Profile Config
+
+1. To add samples in a profile to your Maven project, add the following to your
+`pom.xml`
+
+    ```xml
+    <project>
+      [...]
+      <profiles>
+        <profile>
+          <id>enable-samples</id>
+          <modules>
+            <module>sample</module>
+          </modules>
+        </profile>
+      </profiles>
+      [...]
+    </project>
+    ```
+
+2. [Activate](#profile-activation) the profile.
+3. Define your samples in a normal Maven project in the `samples/` directory
+
+### Profile Activation
+
+To include code samples when building and testing the project, enable the 
+`enable-samples` Maven profile.
+
+#### Command line
+
+To activate the Maven profile on the command line add `-Penable-samples` to your
+Maven command.
+
+#### Maven `settings.xml`
+
+To activate the Maven profile in your `~/.m2/settings.xml` add an entry of
+`enable-samples` following the instructions in [Active Profiles][2].
+
+This method has the benefit of applying to all projects you build (and is
+respected by IntelliJ IDEA) and is recommended if you are going to be
+contributing samples to several projects.
+
+#### IntelliJ IDEA
+
+To activate the Maven Profile inside IntelliJ IDEA, follow the instructions in
+[Activate Maven profiles][3] to activate `enable-samples`.
+
+[1]: https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account
+[2]: https://maven.apache.org/settings.html#Active_Profiles
+[3]: https://www.jetbrains.com/help/idea/work-with-maven-profiles.html#activate_maven_profiles