Skip to content

Update CONTRIBUTING, ISSUE_TEMPLATE, and parent README #1503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 8, 2019
Merged

Update CONTRIBUTING, ISSUE_TEMPLATE, and parent README #1503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4698b04
Update ReadMe
averikitsch Jul 3, 2019
67783ab
Move to match the new github style
averikitsch Jul 3, 2019
522b67e
Update contributing
averikitsch Jul 3, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions ISSUE_TEMPLATE.md → .github/ISSUE_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,8 @@
<!-- If this is a question about a specific product or for debugging help, please
ask your question on [Stack Overflow](https://stackoverflow.com/) using
appropriate tags. This improves visibility of your question and the answer for
additional users. -->

## In which file did you encounter the issue?

<!-- Please provide the full path to the file, to avoid ambiguity -->
Expand Down
105 changes: 68 additions & 37 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
# How to become a contributor and submit your own code

* [Contributor License Agreements](#Contributor-License-Agreements)
* [Contributing a Patch](#Contributing-a-Patch)
* [Contributing a new sample](#Contributing-a-new-sample)
* [Contributing a Patch or New Sample](#Contributing-a-Patch)
* [Build Tools](#build-tools)
* [Integration Testing](#testing)
* [Style](#Style)
Expand All @@ -26,32 +25,37 @@ 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
## Contributing a Patch or New Sample

1. Submit an issue describing your proposed change to the repo in question.
1. The repo owner will respond to your issue promptly.
1. If your proposed change is accepted, and you haven't already done so, sign a
Contributor License Agreement (see details above).
1. Fork the desired repo, develop and test your code changes.
1. Ensure that your code adheres to the existing style in the sample to which
you are contributing.
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.

## Contributing a new sample
## Build Tools

1. See the [SAMPLE_FORMAT.md](SAMPLE_FORMAT.md) for guidelines on the preferred sample format.
All new samples should build and run integration tests with both [Maven](https://maven.apache.org/) and [Gradle](https://gradle.org/).

## Integration Testing

## Build Tools
All samples must have Integration Tests that run with Maven and Gradle

For instructions regarding development environment setup, please visit [the documentation](https://cloud.google.com/java/docs/setup). All new samples should build and run integration tests with both [Maven](https://maven.apache.org/) and [Gradle](https://gradle.org/).
* 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/).

## Testing
### Running Tests Locally

All samples must have Integration Tests (ie. They need to run against a real service) that run with
`mvn verify` & `gradle build test`. If we need to enable an API, let us know.
Run tests locally with commands:
* Maven: `mvn verify`
* Gradle: `gradle build test`


### Gradle Specifcs
Your `build.gradle` should have the following section:

```groovy
Expand All @@ -72,9 +76,34 @@ test {
}
```

### Keys and Secrets
### 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**
Add a note in the pull request, if an API needs to be enable in the testing
project.

Please contact a Java DPE for instructions before adding to Travis.
* **Cloud resources**
Most Java samples create the Cloud resources that they need to run. If this
is resource intensive or not possible, add a note in the pull request for the
resource to be added 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

Expand All @@ -90,34 +119,37 @@ tool or IntelliJ plugin.

[google-java-format]: https://github.com/google/google-java-format

### Running the Linter

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

```shell
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.

### 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.
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</groupId>
<artifactId>doc-samples</artifactId>
<version>1.0.0</version>
<!-- Change relativePath to point to the root directory. -->
<relativePath>../..</relativePath>
<version>1.0.11</version>
</parent>
```

This is just used for testing. The sample should build without a parent defined.
### Running the Linter

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

```shell
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

Expand All @@ -128,5 +160,4 @@ 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)

options](https://cloud.google.com/dataflow/pipelines/specifying-exec-params).
60 changes: 32 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,44 +1,48 @@
# java-docs-samples
# Google Cloud Platform Java Samples

![Kokoro Build Status](https://storage.googleapis.com/cloud-devrel-kokoro-resources/java/badges/java-docs-samples.png)
[![Coverage Status](https://codecov.io/gh/GoogleCloudPlatform/java-docs-samples/branch/master/graph/badge.svg)](https://codecov.io/gh/GoogleCloudPlatform/java-docs-samples)

<a href="https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/java-docs-samples&page=editor&open_in_editor=README.md">
<img alt="Open in Cloud Shell" src ="http://gstatic.com/cloudssh/images/open-btn.png"></a>

While this library is still supported, we suggest trying the newer [Cloud Client Library](https://developers.google.com/api-client-library/java/apis/vision/v1) for Google Cloud Vision, especially for new projects. For more information, please see the notice on the [API Client Library Page](https://developers.google.com/api-client-library/java/apis/vision/v1).
This repository holds sample code written in Go that demonstrates the
[Google Cloud Platform](https://cloud.google.com/docs/).

This is a repository that contains java code snippets on [Cloud Platform Documentation](https://cloud.google.com/docs/).
Some samples have accompanying guides on <cloud.google.com>. See respective
README files for details.

Technology Samples:
## Set Up

* [Bigquery](bigquery)
* [Data Catalog](datacatalog)
* [Datastore](datastore)
* [Endpoints](endpoints)
* [Identity-Aware Proxy](iap)
* [Key Management Service](kms)
* [Logging](logging)
* [Monitoring](monitoring)
* [Natural Language](language)
* [PubSub](pubsub)
* [Cloud Spanner](spanner)
* [Speech](speech)
* [Cloud Storage](storage)
* [Translate](translate)
* [Vision](vision)
1. [Set up your Java Development Environment](https://cloud.google.com/java/docs/setup)

## Credentials Example
1. Clone this repository:

The documentation for [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials).
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

`BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();`
1. Obtain authentication credentials.

The client library looks for credentials using the following rules:
Create local credentials by running the following command and following the
oauth2 flow (read more about the command [here][auth_command]):

1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable, pointing to a service account key JSON file path.
2. Cloud SDK credentials `gcloud auth application-default login`
3. App Engine standard environment credentials.
4. Compute Engine credentials.
gcloud auth application-default login

You can override this behavior using setCredentials in `BigQueryOptions.newBuilder()` by adding `setCredentials(Credentials credentials)` from [ServiceOptions.builder](http://googlecloudplatform.github.io/google-cloud-java/0.12.0/apidocs/com/google/cloud/ServiceOptions.Builder.html#setCredentials-com.google.auth.Credentials-) and [Credentials](http://google.github.io/google-auth-library-java/releases/0.6.0/apidocs/com/google/auth/Credentials.html?is-external=true).
Or manually set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable
to point to a service account key JSON file path.

Learn more at [Setting Up Authentication for Server to Server Production Applications](ADC).

*Note:* Application Default Credentials is able to implicitly find the credentials as long as the application is running on Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions.

## Contributing

* See the [Contributing Guide](CONTRIBUTING.md)

## Licensing

* See [LICENSE](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-
[auth_command]: https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default/login