From 7c9d4941e0c175f39c655abe95990db809de986b Mon Sep 17 00:00:00 2001 From: Tim Swast Date: Fri, 18 Mar 2016 13:13:48 -0700 Subject: [PATCH] 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 0a9b3c65..fe62e80d 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)