1*882aa7c7SMatt Gilbride# How to Contribute 2*882aa7c7SMatt Gilbride 3*882aa7c7SMatt GilbrideWe'd love to accept your patches and contributions to this project. There are 4*882aa7c7SMatt Gilbridejust a few small guidelines you need to follow. 5*882aa7c7SMatt Gilbride 6*882aa7c7SMatt Gilbride## Contributor License Agreement 7*882aa7c7SMatt Gilbride 8*882aa7c7SMatt GilbrideContributions to this project must be accompanied by a Contributor License 9*882aa7c7SMatt GilbrideAgreement. You (or your employer) retain the copyright to your contribution; 10*882aa7c7SMatt Gilbridethis simply gives us permission to use and redistribute your contributions as 11*882aa7c7SMatt Gilbridepart of the project. Head over to <https://cla.developers.google.com/> to see 12*882aa7c7SMatt Gilbrideyour current agreements on file or to sign a new one. 13*882aa7c7SMatt Gilbride 14*882aa7c7SMatt GilbrideYou generally only need to submit a CLA once, so if you've already submitted one 15*882aa7c7SMatt Gilbride(even if it was for a different project), you probably don't need to do it 16*882aa7c7SMatt Gilbrideagain. 17*882aa7c7SMatt Gilbride 18*882aa7c7SMatt Gilbride## Code reviews 19*882aa7c7SMatt Gilbride 20*882aa7c7SMatt GilbrideAll submissions, including submissions by project members, require review. We 21*882aa7c7SMatt Gilbrideuse GitHub pull requests for this purpose. Consult 22*882aa7c7SMatt Gilbride[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more 23*882aa7c7SMatt Gilbrideinformation on using pull requests. 24*882aa7c7SMatt Gilbride 25*882aa7c7SMatt Gilbride## Community Guidelines 26*882aa7c7SMatt Gilbride 27*882aa7c7SMatt GilbrideThis project follows 28*882aa7c7SMatt Gilbride[Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). 29*882aa7c7SMatt Gilbride 30*882aa7c7SMatt Gilbride## Building the project 31*882aa7c7SMatt Gilbride 32*882aa7c7SMatt GilbrideTo build, package, and run all unit tests run the command 33*882aa7c7SMatt Gilbride 34*882aa7c7SMatt Gilbride``` 35*882aa7c7SMatt Gilbridemvn clean verify 36*882aa7c7SMatt Gilbride``` 37*882aa7c7SMatt Gilbride 38*882aa7c7SMatt Gilbride### Running Integration tests 39*882aa7c7SMatt Gilbride 40*882aa7c7SMatt GilbrideTo include integration tests when building the project, you need access to 41*882aa7c7SMatt Gilbridea GCP Project with a valid service account. 42*882aa7c7SMatt Gilbride 43*882aa7c7SMatt GilbrideFor instructions on how to generate a service account and corresponding 44*882aa7c7SMatt Gilbridecredentials JSON see: [Creating a Service Account][1]. 45*882aa7c7SMatt Gilbride 46*882aa7c7SMatt GilbrideThen run the following to build, package, run all unit tests and run all 47*882aa7c7SMatt Gilbrideintegration tests. 48*882aa7c7SMatt Gilbride 49*882aa7c7SMatt Gilbride```bash 50*882aa7c7SMatt Gilbrideexport GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account.json 51*882aa7c7SMatt Gilbridemvn -Penable-integration-tests clean verify 52*882aa7c7SMatt Gilbride``` 53*882aa7c7SMatt Gilbride 54*882aa7c7SMatt Gilbride## Code Samples 55*882aa7c7SMatt Gilbride 56*882aa7c7SMatt GilbrideAll code samples must be in compliance with the [java sample formatting guide][3]. 57*882aa7c7SMatt GilbrideCode Samples must be bundled in separate Maven modules. 58*882aa7c7SMatt Gilbride 59*882aa7c7SMatt GilbrideThe samples must be separate from the primary project for a few reasons: 60*882aa7c7SMatt Gilbride1. Primary projects have a minimum Java version of Java 8 whereas samples can have 61*882aa7c7SMatt Gilbride Java version of Java 11. Due to this we need the ability to 62*882aa7c7SMatt Gilbride selectively exclude samples from a build run. 63*882aa7c7SMatt Gilbride2. Many code samples depend on external GCP services and need 64*882aa7c7SMatt Gilbride credentials to access the service. 65*882aa7c7SMatt Gilbride3. Code samples are not released as Maven artifacts and must be excluded from 66*882aa7c7SMatt Gilbride release builds. 67*882aa7c7SMatt Gilbride 68*882aa7c7SMatt Gilbride### Building 69*882aa7c7SMatt Gilbride 70*882aa7c7SMatt Gilbride```bash 71*882aa7c7SMatt Gilbridemvn clean verify 72*882aa7c7SMatt Gilbride``` 73*882aa7c7SMatt Gilbride 74*882aa7c7SMatt GilbrideSome samples require access to GCP services and require a service account: 75*882aa7c7SMatt Gilbride 76*882aa7c7SMatt Gilbride```bash 77*882aa7c7SMatt Gilbrideexport GOOGLE_APPLICATION_CREDENTIALS=/path/to/service/account.json 78*882aa7c7SMatt Gilbridemvn clean verify 79*882aa7c7SMatt Gilbride``` 80*882aa7c7SMatt Gilbride 81*882aa7c7SMatt Gilbride### Code Formatting 82*882aa7c7SMatt Gilbride 83*882aa7c7SMatt GilbrideCode in this repo is formatted with 84*882aa7c7SMatt Gilbride[google-java-format](https://github.com/google/google-java-format). 85*882aa7c7SMatt GilbrideTo run formatting on your project, you can run: 86*882aa7c7SMatt Gilbride``` 87*882aa7c7SMatt Gilbridemvn com.coveo:fmt-maven-plugin:format 88*882aa7c7SMatt Gilbride``` 89*882aa7c7SMatt Gilbride 90*882aa7c7SMatt Gilbride[1]: https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account 91*882aa7c7SMatt Gilbride[2]: https://maven.apache.org/settings.html#Active_Profiles 92*882aa7c7SMatt Gilbride[3]: https://github.com/GoogleCloudPlatform/java-docs-samples/blob/main/SAMPLE_FORMAT.md