Skip to content

Latest commit

 

History

History
162 lines (119 loc) · 5.65 KB

CONTRIBUTING.md

File metadata and controls

162 lines (119 loc) · 5.65 KB
Raw

How to become a contributor and submit your own code

Contributor License Agreements

We'd love to accept your sample apps and patches! Before we can take them, we have to jump a couple of legal hurdles.

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.
  • If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.

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.
  2. Set up your Java Developer Environment.
  3. Fork the repo.
  4. Develop and test your code.
  5. Ensure that your code adheres to the SAMPLE_FORMAT.md guidelines.
  6. Ensure that your code has an appropriate set of unit tests which all pass.
  7. Submit a pull request.
  8. A maintainer will review the pull request and make comments.

Build Tools

All new samples should build and run integration tests with both Maven and Gradle.

Integration Testing

All samples must have integration tests that run with Maven and Gradle

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:

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.

Style

Samples in this repository follow the Google Java Style Guide. This is enforced using the Maven Checkstyle Plugin.

Use the 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.

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 repository.

<!--
    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</groupId>
  <artifactId>doc-samples</artifactId>
  <version>1.0.11</version>
</parent>

Running the Linter

To run the checkstyle & ErrorProne plugins on an existing sample, run

mvn clean verify -DskipTests

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.

Parsing Command-Line Arguments in Samples

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 library.

Dataflow samples are an exception to this rule, since Dataflow has its own method for setting custom options.