Update Guidelines (GoogleCloudPlatform#2504)

lesv · web-flow · commit e12cc5c26c18 · 2020-03-27T14:10:51.000-07:00
* Update Guidelines

* Update Contributing to closer match the current cononical version.
* Add PULL_REQUEST_TEMPLATE
* Update README to closer add the License requirement from the cononical version.
* Major revision of SAMPLE_FORMAT

* apply comments

* Update SAMPLE_FORMAT.md

* Discourage use of CLI.
* Discourage use of the default package.

* Dane's feedback

* remove xtra stuff in test labels for Region_Tags
* Fix some language and change from CONTRIBUTING to README for resources
* Parallel Streams - fix language

* two more from Dane

* Fix path
* Add a path.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,9 @@
+Fixes #<issue_number_goes_here>
+
+> It's a good idea to open an issue first for discussion.
+
+- [ ] Tests pass
+- [ ] Appropriate changes to README are included in PR
+- [ ] API's need to be enabled to test (tell us)
+- [ ] Environment Variables need to be set (ask us to set them)
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,162 +1,37 @@
-# How to become a contributor and submit your own code
+# How to Contribute
 
-* [Contributor License Agreements](#Contributor-License-Agreements)
-* [Contributing a Patch or New Sample](#Contributing-a-Patch)
-* [Build Tools](#build-tools)
-* [Integration Testing](#testing)
-* [Style](#Style)
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
 
-## Contributor License Agreements
+## Contributor License Agreement
 
-We'd love to accept your sample apps and patches! Before we can take them, we
-have to jump a couple of legal hurdles.
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
 
-Please fill out either the individual or corporate Contributor License Agreement
-(CLA).
-
-  * If you are an individual writing original source code and you're sure you
-    own the intellectual property, then you'll need to sign an [individual
-    CLA](https://developers.google.com/open-source/cla/individual).
-  * If you work for a company that wants to allow you to contribute your work,
-    then you'll need to sign a [corporate
-    CLA](https://developers.google.com/open-source/cla/corporate).
-
-Follow either of the two links above to access the appropriate CLA and
-instructions for how to sign and return it. Once we receive it, we'll be able to
-accept your pull requests.
-
-## Contributing a Patch or New Sample
-
-1. Sign a [Contributor License Agreement](#Contributor-License-Agreements).
-1. Set up your [Java Developer Environment](https://cloud.google.com/java/docs/setup).
-1. Fork the repo.
-1. Develop and test your code.
-1. Ensure that your code adheres to the [SAMPLE_FORMAT.md](SAMPLE_FORMAT.md)
-guidelines.
-1. Ensure that your code has an appropriate set of unit tests which all pass.
-1. Submit a pull request.
-1. A maintainer will review the pull request and make comments.
-
-## Build Tools
-
-All new samples should build and run integration tests with both [Maven](https://maven.apache.org/) and [Gradle](https://gradle.org/).
-
-## Integration Testing
-
-All samples must have integration tests that run with Maven and Gradle
-
-* Test Library: [JUnit4](https://junit.org/junit4/)
-* Test Runner: [Maven Failsafe plugin](https://maven.apache.org/surefire/maven-failsafe-plugin/) and [Maven Surefire plugin](https://maven.apache.org/surefire/maven-surefire-plugin/).
-
-### Running Tests Locally
-
-Run tests locally with commands:
-
-* Maven: `mvn verify`
-* Gradle: `gradle build test`
-
-### Gradle Specifcs
-Your `build.gradle` should have the following section:
-
-```groovy
-
-test {
-  useJUnit()
-  testLogging.showStandardStreams = true
-  beforeTest { descriptor ->
-     logger.lifecycle("test: " + descriptor + "  Running")
-  }
-
-  onOutput { descriptor, event ->
-     logger.lifecycle("test: " + descriptor + ": " + event.message )
-  }
-  afterTest { descriptor, result ->
-    logger.lifecycle("test: " + descriptor + ": " + result )
-  }
-}
-```
-
-### Other Testing Set Up
-
-Most samples require a GCP project and billing account. Keep the following in
-mind when setting up tests.
-
-* **Environment variables**  
-  Minimize additional environment variables that need to be set to run the tests.
-  If you do require additional environment variables, they should be added to
-  `run_tests.sh`.
-
-  Existing environment variables include:
-  * `GOOGLE_APPLICATION_CREDENTIALS`
-  * `GOOGLE_CLOUD_PROJECT`
-  * `PROJECT_ID`
-
-* **API library**  
-  If an API needs to be enabled in the testing project, add this information to the
-  directory's CONTRIBUTING.md file. If there is no CONTRIBUTING.md file, add one in your PR.
-
-* **Cloud resources**  
-  Most Java samples create the Cloud resources that they need to run. If this
-  is resource intensive or not possible, add instructions to the directory's CONTRIBUTING.md file
-  to add the resource to the testing project.
-
-* **Keys and Secrets**
-  Add a note in the pull request, in order for a Java maintainer to assist you
-  in adding keys and secrets to the testing project.
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
 
 ## Style
 
-Samples in this repository follow the [Google Java Style Guide][java-style].
-This is enforced using the [Maven Checkstyle Plugin][checkstyle-plugin].
-
-[java-style]: https://google.github.io/styleguide/javaguide.html
-[checkstyle-plugin]: https://maven.apache.org/plugins/maven-checkstyle-plugin/
-
-Use the [google-java-format][google-java-format] tool to automatically reformat
-your source code to adhere to the style guide. It is available as a command-line
-tool or IntelliJ plugin.
-
-[google-java-format]: https://github.com/google/google-java-format
-
-### Adding the Checkstyle Plugin to New Samples
-
-The samples in this repository use a common parent POM to define plugins used
-for linting and testing. Add the following to your sample POM to ensure that it
-uses the common Checkstyle configuration. For more information, see the
-[java-repo-tools](https://github.com/GoogleCloudPlatform/java-repo-tools)
-repository.
-
-```xml
-<!--
-    The parent pom defines common style checks and testing strategies for our samples.
-    Removing or replacing it should not affect the execution of the samples in anyway.
-  -->
-<parent>
-  <groupId>com.google.cloud.samples</groupId>
-  <artifactId>shared-configuration</artifactId>
-  <version>1.0.13</version>
-</parent>
-```
-
-### Running the Linter
+All code should follow the [Sample Format Guidelines](/java-docs-samples/blob/master/SAMPLE_FORMAT.md)
 
-To run the checkstyle & ErrorProne plugins on an existing sample, run
+## Code reviews
 
-```shell
-mvn clean verify -DskipTests
-```
+Change to samples should be reviewed by both a product stakeholder for accuracy as well as a member
+of java-samples-reviewers@ to ensure the sample format and best practices for Java are used.
 
-The `-DskipTests` is optional. It is useful if you want to verify that your code
-builds and adheres to the style guide without waiting for tests to complete.
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
 
+## Community Guidelines
 
-### Parsing Command-Line Arguments in Samples
+This project follows 
+[Google's Open Source Community Guidelines](https://opensource.google/conduct/).
 
-Simple command-line samples with only positional arguments should use the
-`args` argument to `main(String... args)` directly. A command-line sample
-which has optional parameters should use the [Apache Commons
-CLI](https://commons.apache.org/proper/commons-cli/index.html) library.
 
-Dataflow samples are an exception to this rule, since Dataflow has [its own
-method for setting custom
-options](https://cloud.google.com/dataflow/pipelines/specifying-exec-params).
diff --git a/README.md b/README.md
@@ -42,6 +42,29 @@ README files for details.
 
 * See [LICENSE](LICENSE)
 
+## Source Code Headers
+
+Every file containing source code must include copyright and license
+information. This includes any JS/CSS files that you might be serving out to
+browsers. (This is to help well-intentioned people avoid accidental copying that
+doesn't comply with the license.)
+
+Apache header:
+
+    Copyright 2020 Google LLC
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
 [ADC]: https://developers.google.com/identity/protocols/application-default-credentials
 [cred]: http://google.github.io/google-auth-library-java/releases/0.6.0/apidocs/com/google/auth/Credentials.html?is-external=true
 [options]: http://googlecloudplatform.github.io/google-cloud-java/0.12.0/apidocs/com/google/cloud/ServiceOptions.Builder.html#setCredentials-com.google.auth.Credentials-
diff --git a/SAMPLE_FORMAT.md b/SAMPLE_FORMAT.md
