From 26e3280124de8eace6f9e482ecb605f159f1ca42 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Tue, 1 Mar 2016 20:42:28 +0000 Subject: [PATCH 01/16] Initial empty repository From f8b4964b97fb916326f01171a6a8d7057bb03c62 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Tue, 1 Mar 2016 15:13:07 -0800 Subject: [PATCH 02/16] Initialize the repository. Adds shared pom.xml and google-checks.xml. I also add a test directory to check that the pom works / is well-formed. --- .gitignore | 23 ++ CONTRIBUTING.md | 35 +++ LICENSE | 201 ++++++++++++++++ README.md | 19 ++ google-checks.xml | 220 ++++++++++++++++++ pom.xml | 113 +++++++++ test/README.md | 5 + test/pom.xml | 48 ++++ .../com/google/cloud/samples/test/App.java | 30 +++ .../google/cloud/samples/test/AppTest.java | 33 +++ 10 files changed, 727 insertions(+) create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 google-checks.xml create mode 100644 pom.xml create mode 100644 test/README.md create mode 100644 test/pom.xml create mode 100644 test/src/main/java/com/google/cloud/samples/test/App.java create mode 100644 test/src/test/java/com/google/cloud/samples/test/AppTest.java diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000000..0f42824f184 --- /dev/null +++ b/.gitignore @@ -0,0 +1,23 @@ +*.class + +# Mobile Tools for Java (J2ME) +.mtj.tmp/ + +# Package Files # +*.jar +*.war +*.ear + +# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml +hs_err_pid* + +# Maven +target/ +pom.xml.tag +pom.xml.releaseBackup +pom.xml.versionsBackup +pom.xml.next +release.properties +dependency-reduced-pom.xml +buildNumber.properties +.mvn/timing.properties diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..6736efd943c --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,35 @@ +# 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] + (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 + +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. Refer to the + [Google Cloud Platform Samples Style Guide] + (https://github.com/GoogleCloudPlatform/Template/wiki/style.html) for the + recommended coding standards for this organization. +1. Ensure that your code has an appropriate set of unit tests which all pass. +1. Submit a pull request. diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000000..261eeb9e9f8 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + 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 + + http://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. diff --git a/README.md b/README.md new file mode 100644 index 00000000000..0a9b3c652e5 --- /dev/null +++ b/README.md @@ -0,0 +1,19 @@ +# Cloud Platform Java Repository Tools + +[![Build +Status](https://travis-ci.org/GoogleCloudPlatform/java-repo-tools.svg?branch=master)](https://travis-ci.org/GoogleCloudPlatform/java-repo-tools) + +This is a collection of common tools used to maintain and test Java repositories +in the [GoogleCloudPlaftorm](https://github.com/GoogleCloudPlatform) +organization. + + +## Contributing changes + +- See [CONTRIBUTING.md](CONTRIBUTING.md) + + +## Licensing + +- Apache 2.0 - See [LICENSE](LICENSE) + diff --git a/google-checks.xml b/google-checks.xml new file mode 100644 index 00000000000..bb3d519998e --- /dev/null +++ b/google-checks.xml @@ -0,0 +1,220 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/pom.xml b/pom.xml new file mode 100644 index 00000000000..e1fcc50f263 --- /dev/null +++ b/pom.xml @@ -0,0 +1,113 @@ + + + + 4.0.0 + 1.0.0 + + com.google.cloud + shared-configuration + pom + + + 1 + 1.9.19 + 1.7 + 1.7 + UTF-8 + 1.19.0 + 1.19.0 + UTF-8 + + + + 3.1.0 + + + + test + + + + + + + org.apache.maven.plugins + maven-surefire-plugin + 2.19.1 + + false + + + + + org.apache.maven.plugins + maven-failsafe-plugin + 2.19.1 + + + + integration-test + verify + + + + + + org.apache.maven.plugins + maven-checkstyle-plugin + 2.17 + + google-checks.xml + true + true + true + true + + + check + + + + org.eluder.coveralls + coveralls-maven-plugin + 3.1.0 + + + ${basedir}/target/coverage.xml + + + + + org.codehaus.mojo + cobertura-maven-plugin + 2.6 + + ${basedir}/target + + xml + html + + xml + 256m + + true + + + + + diff --git a/test/README.md b/test/README.md new file mode 100644 index 00000000000..59e4015515c --- /dev/null +++ b/test/README.md @@ -0,0 +1,5 @@ +# Cloud Platform Java Repository Tools Test + +This is a test application for checking that the root [`pom.xml`](../pom.xml) +and [`google-checks.xml`](../google-checks.xml) are working as expected. + diff --git a/test/pom.xml b/test/pom.xml new file mode 100644 index 00000000000..96f42c5f06a --- /dev/null +++ b/test/pom.xml @@ -0,0 +1,48 @@ + + + + 4.0.0 + + com.google.cloud + shared-configuration-test + 1.0 + jar + + + shared-configuration + com.google.cloud + 1.0.0 + .. + + + + + + junit + junit + 4.12 + test + + + com.google.truth + truth + 0.27 + test + + + diff --git a/test/src/main/java/com/google/cloud/samples/test/App.java b/test/src/main/java/com/google/cloud/samples/test/App.java new file mode 100644 index 00000000000..244b1507594 --- /dev/null +++ b/test/src/main/java/com/google/cloud/samples/test/App.java @@ -0,0 +1,30 @@ +/* + * Copyright 2016 Google Inc. All Rights Reserved. + * + * 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 + * + * http://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. + */ + +package com.google.cloud.samples.test; + +/** + * A hello world app to test the parent pom.xml. + */ +public class App { + public static String greeting() { + return "Hello World!"; + } + + public static void main(String[] args) { + System.out.println(App.greeting()); + } +} diff --git a/test/src/test/java/com/google/cloud/samples/test/AppTest.java b/test/src/test/java/com/google/cloud/samples/test/AppTest.java new file mode 100644 index 00000000000..ab7f5095aae --- /dev/null +++ b/test/src/test/java/com/google/cloud/samples/test/AppTest.java @@ -0,0 +1,33 @@ +/* + * Copyright 2016 Google Inc. All Rights Reserved. + * + * 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 + * + * http://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. + */ + +package com.google.cloud.samples.test; + +import static com.google.common.truth.Truth.assertThat; + +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; + +/** + * Unit tests for {@link App}. + */ +@RunWith(JUnit4.class) +public class AppTest { + @Test public void greeting_returnsHelloWorld() { + assertThat(App.greeting()).named("greeting").isEqualTo("Hello World!"); + } +} From 7d5661d123a33d88038d09bf501163fcd9e5cea5 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 3 Mar 2016 16:05:46 -0800 Subject: [PATCH 03/16] Add Travis configuration. --- .travis.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000000..bb7197c540d --- /dev/null +++ b/.travis.yml @@ -0,0 +1,23 @@ +# Copyright 2016 Google Inc. All Rights Reserved. +# +# 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 +# +# http://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. +language: java +jdk: + - oraclejdk7 + - oraclejdk8 +script: mvn verify +after_success: + - mvn clean cobertura:cobertura coveralls:report +branches: + only: + - master From cf3de1a8f1475663a86fa26296c3f7f7c0e9837c Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 3 Mar 2016 16:23:07 -0800 Subject: [PATCH 04/16] Remove unnecessary properties. --- pom.xml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/pom.xml b/pom.xml index e1fcc50f263..7ffce85fa82 100644 --- a/pom.xml +++ b/pom.xml @@ -24,13 +24,7 @@ limitations under the License. pom - 1 - 1.9.19 - 1.7 - 1.7 UTF-8 - 1.19.0 - 1.19.0 UTF-8 From ac6ce48369de6ee41ac15266a5f7da354ce4475d Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 3 Mar 2016 17:20:11 -0800 Subject: [PATCH 05/16] Ignore generated AutoValue classes from checkstyle. --- pom.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/pom.xml b/pom.xml index 7ffce85fa82..8acea9d9a49 100644 --- a/pom.xml +++ b/pom.xml @@ -68,6 +68,7 @@ limitations under the License. google-checks.xml true + **/AutoValue_* true true true From 8d4b9a37a34e73fb9cdb62b9d69cc7cef325706b Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Fri, 4 Mar 2016 10:43:44 -0800 Subject: [PATCH 06/16] Ignore JavaDoc rules in test classes. --- google-checks.xml | 6 +++--- pom.xml | 2 +- suppressions.xml | 27 +++++++++++++++++++++++++++ 3 files changed, 31 insertions(+), 4 deletions(-) create mode 100644 suppressions.xml diff --git a/google-checks.xml b/google-checks.xml index bb3d519998e..aa1e5335b6b 100644 --- a/google-checks.xml +++ b/google-checks.xml @@ -38,9 +38,9 @@ - - - + + + diff --git a/pom.xml b/pom.xml index 8acea9d9a49..af0f46e4365 100644 --- a/pom.xml +++ b/pom.xml @@ -68,10 +68,10 @@ limitations under the License. google-checks.xml true - **/AutoValue_* true true true + suppressions.xml check diff --git a/suppressions.xml b/suppressions.xml new file mode 100644 index 00000000000..22a348c205e --- /dev/null +++ b/suppressions.xml @@ -0,0 +1,27 @@ + + + + + + + + + + + From 344227cb5e73981491ac28b90ed1b9b437c565d1 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 17 Mar 2016 10:33:05 -0700 Subject: [PATCH 07/16] Ignore service account file. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index 0f42824f184..342c18bf686 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +service-account.json + +### Java ### *.class # Mobile Tools for Java (J2ME) From 3c480971a4695268f27cf0f81ea5fb45da35c0b0 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Thu, 17 Mar 2016 11:11:03 -0700 Subject: [PATCH 08/16] Add license header to POM. --- pom.xml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/pom.xml b/pom.xml index af0f46e4365..e86bda86f7b 100644 --- a/pom.xml +++ b/pom.xml @@ -1,4 +1,3 @@ - - + 4.0.0 1.0.0 From 7c9d4941e0c175f39c655abe95990db809de986b Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Fri, 18 Mar 2016 13:13:48 -0700 Subject: [PATCH 09/16] Add instructions for using with subtrees. Subtrees are the primary way I expect people to use the `java-repo-tools` repository. Since it's not a super common workflow, I document the needed steps in the README. --- README.md | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) diff --git a/README.md b/README.md index 0a9b3c652e5..fe62e80db1a 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,169 @@ in the [GoogleCloudPlaftorm](https://github.com/GoogleCloudPlatform) organization. +## Using this repository + +This repository is copied into a subtree of other Java repositories, such as +[java-docs-samples](/GoogleCloudPlatform/java-docs-samples). Note, that a +subtree is just the code copied into a directory, so a regular `git clone` will +continue to work. + + +### Adding to a new repository + +To copy `java-repo-tools` into a subtree of a new repository `my-java-samples`, +first add this repository as a remote. We then fetch all the changes from this +`java-repo-tools`. + +``` +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +``` + +To make it easier to push changes back upstream, create a new branch. + +``` +git checkout -b java-repo-tools java-repo-tools/master +``` + +We can then go back to the `my-java-samples` code and prepare a Pull Request to +add the `java-repo-tools` code in a subtree. + +``` +git checkout master +# Making a new branch ia optional, but recommended to send a pull request to +# start using java-repo-tools. +git checkout -b use-java-repo-tools +git read-tree --prefix=java-repo-tools/ -u java-repo-tools +``` + +Now all the content of `java-repo-tools` will be in the `java-repo-tools/` +directory (which we specified in the `--prefix` command). + +#### Using the Maven configuration + +If all the projects within your `my-java-samples` share a common parent POM for +plugin configuration (like checkstyle). We can then make the +`java-repo-tools/pom.xml` parent of this. + +``` + + + com.google.cloud + shared-configuration + 1.0.0 + java-repo-tools + +``` + +Once this is added to the common parent, all modules will have the same plugin +configuration applied. If the children POMs provide the plugin information +themselves, it will override this configuration, so you should delete any +now-redundant plugin information. + + +#### Examples + +- Adding to repository with an existing parent POM: Pull Request + [java-docs-samples#125][java-docs-samples-125]. + +[java-docs-samples-125]: https://github.com/GoogleCloudPlatform/java-docs-samples/pull/125 + + +### Detecting if you need to synchronize a subtree + +If you haven't done this before, run + +``` +git remote add java-repo-tools +git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +# Optional, but it makes pushing changes upstream easier. +git checkout -b java-repo-tools java-repo-tools/master +``` + +To detect if you have changes in the directory, run + +``` +git fetch java-repo-tools +git diff-tree -p HEAD:java-repo-tools/ java-repo-tools/master +``` + +or to diff against your local `java-repo-tools` branch: + +``` +git diff-tree -p HEAD:java-repo-tools/ java-repo-tools -- +``` + +(The trailing `--` is to say that we want to compare against the branch, not the +directory.) + + +### Pulling changes from Java Repository Tools to a subtree + +To update the `java-repo-tools` directory, if you haven't done this before, run + +``` +git remote add java-repo-tools +git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +git checkout -b java-repo-tools java-repo-tools/master +``` + +To pull the changes when in this branch run + +``` +git pull java-repo-tools master +``` + +To pull the changes back from upstream: + +``` +git checkout java-repo-tools +git pull java-repo-tools master +``` + +Pull them into the main code. + +``` +git checkout master +# Making a new branch is optional, but recommended to send a pull request for +# update. +git checkout -b update-java-repo-tools +git merge --squash -Xsubtree=java-repo-tools/ --no-commit java-repo-tools +``` + +Then you can make any needed changes to make the rest of the repository +compatible with the updated `java-repo-tools` code, commit, push, and send a +Pull Request as you would in the normal flow. + + +### Pushing changes from a subtree upstream to Java Repository Tools + +What if you make changes in your repository and now want to push them upstream? + +Assuming you just commited changes in the `java-repo-tools/` directory of your +`my-main-branch`, to merge the changes into the local `java-repo-tools` branch, +we need to cherry pick this commit using the subtree strategy. It will ignore +any changes to file not in the `java-repo-tools/` directory. + +``` +git checkout java-repo-tools +git cherry-pick -x --strategy=subtree my-main-branch +``` + +After you have committed all the changes you want to your `java-repo-tools` +branch, you can push to the upstream `java-repo-tools` repository with the +following command. (Replace `name-for-remote-branch` with the name you'd like to +give the branch on the `java-repo-tools` repository.) + +``` +git push java-repo-tools java-repo-tools:name-for-remote-branch +``` + +Then, you can send a pull request to the `java-repo-tools` repository. + + ## Contributing changes - See [CONTRIBUTING.md](CONTRIBUTING.md) From c3264a515bbf87d91507a04af8b7cafc182968cb Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Tue, 29 Mar 2016 11:03:56 -0700 Subject: [PATCH 10/16] Remove extra newline in README --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index fe62e80db1a..530593bda09 100644 --- a/README.md +++ b/README.md @@ -82,8 +82,7 @@ now-redundant plugin information. If you haven't done this before, run ``` -git remote add java-repo-tools -git@github.com:GoogleCloudPlatform/java-repo-tools.git +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git git fetch java-repo-tools master # Optional, but it makes pushing changes upstream easier. git checkout -b java-repo-tools java-repo-tools/master From fcbbca5a35aae346ce4c9f483dfde53836130348 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Tue, 29 Mar 2016 11:06:17 -0700 Subject: [PATCH 11/16] Remove another extra newline. --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 530593bda09..19921528260 100644 --- a/README.md +++ b/README.md @@ -110,8 +110,7 @@ directory.) To update the `java-repo-tools` directory, if you haven't done this before, run ``` -git remote add java-repo-tools -git@github.com:GoogleCloudPlatform/java-repo-tools.git +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git git fetch java-repo-tools master git checkout -b java-repo-tools java-repo-tools/master ``` From 2e5da267098a93eb6b23d3b219a6d64a69af0188 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Tue, 29 Mar 2016 10:58:41 -0700 Subject: [PATCH 12/16] Checkstyle fixes. I modify the checkstyle config to have SAME_PACKAGE imports appear before third-party imports. I think this better matches the intent of the import ordering rules in the style guide. https://google.github.io/styleguide/javaguide.html#s3.3.3-import-ordering-and-spacing Expecially since it says the `com.google` imports only appear after static imports if the source file is in the `com.google` package space. (cherry picked from commit 7ca0e7564d4d1a39714d8c90e71d5e408f30f4da) --- google-checks.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/google-checks.xml b/google-checks.xml index aa1e5335b6b..5f1d75b1e7e 100644 --- a/google-checks.xml +++ b/google-checks.xml @@ -167,9 +167,9 @@ - + - + From 638b601fc4c0793c5ffe62370ce9c227c3e74fd6 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 30 Mar 2016 16:24:50 -0700 Subject: [PATCH 13/16] Remove command that was copy-paste error. The pulling changes from Java Repository Tools instructions can now be followed verbatim. --- README.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/README.md b/README.md index 19921528260..26a549777c9 100644 --- a/README.md +++ b/README.md @@ -115,13 +115,7 @@ git fetch java-repo-tools master git checkout -b java-repo-tools java-repo-tools/master ``` -To pull the changes when in this branch run - -``` -git pull java-repo-tools master -``` - -To pull the changes back from upstream: +To pull the latest changes from this `java-repo-tools` repository, run: ``` git checkout java-repo-tools From 3b96c16f45d74c261512cd68e46477e8ec0f4a45 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 30 Mar 2016 16:55:25 -0700 Subject: [PATCH 14/16] Pull in updates from java-repo-tools. --- java-repo-tools/README.md | 155 ++++++++++++++++++++++++++++++ java-repo-tools/google-checks.xml | 4 +- 2 files changed, 157 insertions(+), 2 deletions(-) diff --git a/java-repo-tools/README.md b/java-repo-tools/README.md index 0a9b3c652e5..26a549777c9 100644 --- a/java-repo-tools/README.md +++ b/java-repo-tools/README.md @@ -8,6 +8,161 @@ in the [GoogleCloudPlaftorm](https://github.com/GoogleCloudPlatform) organization. +## Using this repository + +This repository is copied into a subtree of other Java repositories, such as +[java-docs-samples](/GoogleCloudPlatform/java-docs-samples). Note, that a +subtree is just the code copied into a directory, so a regular `git clone` will +continue to work. + + +### Adding to a new repository + +To copy `java-repo-tools` into a subtree of a new repository `my-java-samples`, +first add this repository as a remote. We then fetch all the changes from this +`java-repo-tools`. + +``` +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +``` + +To make it easier to push changes back upstream, create a new branch. + +``` +git checkout -b java-repo-tools java-repo-tools/master +``` + +We can then go back to the `my-java-samples` code and prepare a Pull Request to +add the `java-repo-tools` code in a subtree. + +``` +git checkout master +# Making a new branch ia optional, but recommended to send a pull request to +# start using java-repo-tools. +git checkout -b use-java-repo-tools +git read-tree --prefix=java-repo-tools/ -u java-repo-tools +``` + +Now all the content of `java-repo-tools` will be in the `java-repo-tools/` +directory (which we specified in the `--prefix` command). + +#### Using the Maven configuration + +If all the projects within your `my-java-samples` share a common parent POM for +plugin configuration (like checkstyle). We can then make the +`java-repo-tools/pom.xml` parent of this. + +``` + + + com.google.cloud + shared-configuration + 1.0.0 + java-repo-tools + +``` + +Once this is added to the common parent, all modules will have the same plugin +configuration applied. If the children POMs provide the plugin information +themselves, it will override this configuration, so you should delete any +now-redundant plugin information. + + +#### Examples + +- Adding to repository with an existing parent POM: Pull Request + [java-docs-samples#125][java-docs-samples-125]. + +[java-docs-samples-125]: https://github.com/GoogleCloudPlatform/java-docs-samples/pull/125 + + +### Detecting if you need to synchronize a subtree + +If you haven't done this before, run + +``` +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +# Optional, but it makes pushing changes upstream easier. +git checkout -b java-repo-tools java-repo-tools/master +``` + +To detect if you have changes in the directory, run + +``` +git fetch java-repo-tools +git diff-tree -p HEAD:java-repo-tools/ java-repo-tools/master +``` + +or to diff against your local `java-repo-tools` branch: + +``` +git diff-tree -p HEAD:java-repo-tools/ java-repo-tools -- +``` + +(The trailing `--` is to say that we want to compare against the branch, not the +directory.) + + +### Pulling changes from Java Repository Tools to a subtree + +To update the `java-repo-tools` directory, if you haven't done this before, run + +``` +git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git +git fetch java-repo-tools master +git checkout -b java-repo-tools java-repo-tools/master +``` + +To pull the latest changes from this `java-repo-tools` repository, run: + +``` +git checkout java-repo-tools +git pull java-repo-tools master +``` + +Pull them into the main code. + +``` +git checkout master +# Making a new branch is optional, but recommended to send a pull request for +# update. +git checkout -b update-java-repo-tools +git merge --squash -Xsubtree=java-repo-tools/ --no-commit java-repo-tools +``` + +Then you can make any needed changes to make the rest of the repository +compatible with the updated `java-repo-tools` code, commit, push, and send a +Pull Request as you would in the normal flow. + + +### Pushing changes from a subtree upstream to Java Repository Tools + +What if you make changes in your repository and now want to push them upstream? + +Assuming you just commited changes in the `java-repo-tools/` directory of your +`my-main-branch`, to merge the changes into the local `java-repo-tools` branch, +we need to cherry pick this commit using the subtree strategy. It will ignore +any changes to file not in the `java-repo-tools/` directory. + +``` +git checkout java-repo-tools +git cherry-pick -x --strategy=subtree my-main-branch +``` + +After you have committed all the changes you want to your `java-repo-tools` +branch, you can push to the upstream `java-repo-tools` repository with the +following command. (Replace `name-for-remote-branch` with the name you'd like to +give the branch on the `java-repo-tools` repository.) + +``` +git push java-repo-tools java-repo-tools:name-for-remote-branch +``` + +Then, you can send a pull request to the `java-repo-tools` repository. + + ## Contributing changes - See [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/java-repo-tools/google-checks.xml b/java-repo-tools/google-checks.xml index aa1e5335b6b..5f1d75b1e7e 100644 --- a/java-repo-tools/google-checks.xml +++ b/java-repo-tools/google-checks.xml @@ -167,9 +167,9 @@ - + - + From 810d4a7ae89c87a807017b7630866cf65c336426 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 30 Mar 2016 16:58:56 -0700 Subject: [PATCH 15/16] Update README.md --- README.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/README.md b/README.md index 26a549777c9..ec275f20d90 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,19 @@ git checkout master # Making a new branch ia optional, but recommended to send a pull request to # start using java-repo-tools. git checkout -b use-java-repo-tools +``` + +So that we can pull future updates from the `java-repo-tools` repository, we +merge histories. This way we won't get unnecessary conflicts when pulling changes +in. + +``` +git merge -s ours --no-commit java-repo-tools/master +``` + +Finally, read the `java-repo-tools` into a subtree. + +``` git read-tree --prefix=java-repo-tools/ -u java-repo-tools ``` From d15620157ae303e6a75b6573ce234ca1408bb7d7 Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Wed, 30 Mar 2016 17:07:27 -0700 Subject: [PATCH 16/16] Add much easier steps for pulling in changes The instructions here are much easier to follow and avoid unnecessary conflicts: https://help.github.com/articles/about-git-subtree-merges/ --- README.md | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ec275f20d90..de5effc04e8 100644 --- a/README.md +++ b/README.md @@ -96,15 +96,12 @@ If you haven't done this before, run ``` git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git -git fetch java-repo-tools master -# Optional, but it makes pushing changes upstream easier. -git checkout -b java-repo-tools java-repo-tools/master ``` To detect if you have changes in the directory, run ``` -git fetch java-repo-tools +git fetch java-repo-tools master git diff-tree -p HEAD:java-repo-tools/ java-repo-tools/master ``` @@ -124,25 +121,16 @@ To update the `java-repo-tools` directory, if you haven't done this before, run ``` git remote add java-repo-tools git@github.com:GoogleCloudPlatform/java-repo-tools.git -git fetch java-repo-tools master -git checkout -b java-repo-tools java-repo-tools/master ``` To pull the latest changes from this `java-repo-tools` repository, run: -``` -git checkout java-repo-tools -git pull java-repo-tools master -``` - -Pull them into the main code. - ``` git checkout master # Making a new branch is optional, but recommended to send a pull request for # update. git checkout -b update-java-repo-tools -git merge --squash -Xsubtree=java-repo-tools/ --no-commit java-repo-tools +git pull -s subtree java-repo-tools master ``` Then you can make any needed changes to make the rest of the repository @@ -176,6 +164,10 @@ git push java-repo-tools java-repo-tools:name-for-remote-branch Then, you can send a pull request to the `java-repo-tools` repository. +## References + +- [GitHub's subtree merge reference](https://help.github.com/articles/about-git-subtree-merges/) + ## Contributing changes - See [CONTRIBUTING.md](CONTRIBUTING.md)