CONTRIBUTING.md - cos/tools - Git at Google

 # How to contribute

 We'd love to accept your patches and contributions to this project. There are
 just a few small guidelines you need to follow.

 ## Contributor License Agreement

 Contributions to this project must be accompanied by a Contributor License
 Agreement (CLA). You (or your employer) retain the copyright to your
 contribution; this simply gives us permission to use and redistribute your
 contributions as part of the project. Head over to
 <https://cla.developers.google.com/> to see your current agreements on file or
 to sign a new one.

 You generally only need to submit a CLA once, so if you've already submitted one
 (even if it was for a different project), you probably don't need to do it
 again.

 ## Checking out source

 ### Set up git

 If you haven't already, configure your git user email and name:

 ```
 git config --global user.email "<your-email>@example.com"
 git config --global user.name "Your Name"
 ```

 ### Checkout

 With your git configured, you can now checkout the source with:

 ```
 git clone https://cos.googlesource.com/cos/tools && (cd tools && f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f)
 ```

 The last command not only clones the repository but also adds a git pre-commit
 hook that will be explained below in "Making changes".

 ### Unit Testing

 Install `bazel` and `mtools`, and ensure `python` is an executable in your
 `$PATH`, pointing to a Python 3 binary. The full suite of unit tests can be
 initiated with

 ```
 bazel test ...
 ```

 Unit tests can also be run using `run_unit_tests.sh`. The script runs all unit
 tests under src/pkg and src/cmd. These unit tests are a part of presubmits for
 changes in cos/tools.

 ### Integration Testing

 Integration tests for cos-customizer are located under `testing/`.
 `run_builds.sh` launches dozens of simultaneous cloud builds and waits for the
 status of each build and reports back failures. It is used in two ways in this
 repository:
 - To run  cos-customizer integration tests (20+ concurrent builds in
   Cloud Build). Minimum quota requirements include ~10 K80s in us-west1.
 - To publish container images in src/cmd to AR (8+ concurrent builds)
 ```
 ./run_builds.sh -p <GCP project name> -m <test|publish>
 ```
 cos-customizer integration tests are run as postsubmits. Ensure that the
 postsubmits are successful after submitting a change. The postsubmit builds
 can be monitored on the CloudBuild [dashboard](https://pantheon.corp.google.com/cloud-build/builds?e=13803378&jsmode=o&mods=allow_workbench_image_override&project=google.com:cloud-image-docker-builder)
 for project `google.com:cloud-image-docker-builder`.

 ## Making changes

 The typical git workflow applies here. You can use `git checkout -b` to create a
 branch and `git commit` to commit local changes. The pre-commit hook that was
 downloaded earlier will insert a Gerrit (Gerrit is explained below) Change-Id
 into every local commit you make. This Change-Id is specific to Gerrit and
 defines a change: one change and the corresponding review in Gerrit will have
 one Change-Id. If a Change-Id is not provided in the commit message, Gerrit will
 reject the commit. While you can manually add a Change-Id later, it's strongly
 recommended you include it from the start, when you clone the repository.

 ## Code reviews

 All submissions, including submissions by project members, require review. We
 use [Gerrit](https://gerrit-review.googlesource.com/Documentation/) for this
 purpose.

 ### Register with Gerrit

 Before you can request code reviews, you need to register with Gerrit first. You
 can do that by going to <https://cos-review.googlesource.com> and clicking "Sign
 in" at the top right corner.

 ### Set up git cookies

 You will also need to generate and configure your git cookies in order to push
 changes to Gerrit. The following steps help you with that:

 1.  Go to https://cos-review.googlesource.com/new-password
 1.  Log in with your google account
 1.  Follow the on-screen directions page to set up/append to your
     `~/.gitcookies` file
 1.  Verify that your cookies are correctly setup:

     ```
     git ls-remote https://cos.googlesource.com/cos/tools.git
     ```

 ### Upload a CL

 ```
 git push origin HEAD:refs/for/master
 ```

 The command will print a URL to the CL that has just been uploaded. You can
 follow the URL to the Gerrit UI and add reviewers from there.

 ## Community guidelines

 This project follows
 [Google's Open Source Community Guidelines](https://opensource.google/conduct/).
	# How to contribute

	We'd love to accept your patches and contributions to this project. There are
	just a few small guidelines you need to follow.

	## Contributor License Agreement

	Contributions to this project must be accompanied by a Contributor License
	Agreement (CLA). You (or your employer) retain the copyright to your
	contribution; this simply gives us permission to use and redistribute your
	contributions as part of the project. Head over to
	<https://cla.developers.google.com/> to see your current agreements on file or
	to sign a new one.

	You generally only need to submit a CLA once, so if you've already submitted one
	(even if it was for a different project), you probably don't need to do it
	again.

	## Checking out source

	### Set up git

	If you haven't already, configure your git user email and name:

	```
	git config --global user.email "<your-email>@example.com"
	git config --global user.name "Your Name"
	```

	### Checkout

	With your git configured, you can now checkout the source with:

	```
	git clone https://cos.googlesource.com/cos/tools && (cd tools && f=`git rev-parse --git-dir`/hooks/commit-msg ; mkdir -p $(dirname $f) ; curl -Lo $f https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x $f)
	```

	The last command not only clones the repository but also adds a git pre-commit
	hook that will be explained below in "Making changes".

	### Unit Testing

	Install `bazel` and `mtools`, and ensure `python` is an executable in your
	`$PATH`, pointing to a Python 3 binary. The full suite of unit tests can be
	initiated with

	```
	bazel test ...
	```

	Unit tests can also be run using `run_unit_tests.sh`. The script runs all unit
	tests under src/pkg and src/cmd. These unit tests are a part of presubmits for
	changes in cos/tools.

	### Integration Testing

	Integration tests for cos-customizer are located under `testing/`.
	`run_builds.sh` launches dozens of simultaneous cloud builds and waits for the
	status of each build and reports back failures. It is used in two ways in this
	repository:
	- To run cos-customizer integration tests (20+ concurrent builds in
	Cloud Build). Minimum quota requirements include ~10 K80s in us-west1.
	- To publish container images in src/cmd to AR (8+ concurrent builds)
	```
	./run_builds.sh -p <GCP project name> -m <test\|publish>
	```
	cos-customizer integration tests are run as postsubmits. Ensure that the
	postsubmits are successful after submitting a change. The postsubmit builds
	can be monitored on the CloudBuild [dashboard](https://pantheon.corp.google.com/cloud-build/builds?e=13803378&jsmode=o&mods=allow_workbench_image_override&project=google.com:cloud-image-docker-builder)
	for project `google.com:cloud-image-docker-builder`.

	## Making changes

	The typical git workflow applies here. You can use `git checkout -b` to create a
	branch and `git commit` to commit local changes. The pre-commit hook that was
	downloaded earlier will insert a Gerrit (Gerrit is explained below) Change-Id
	into every local commit you make. This Change-Id is specific to Gerrit and
	defines a change: one change and the corresponding review in Gerrit will have
	one Change-Id. If a Change-Id is not provided in the commit message, Gerrit will
	reject the commit. While you can manually add a Change-Id later, it's strongly
	recommended you include it from the start, when you clone the repository.

	## Code reviews

	All submissions, including submissions by project members, require review. We
	use [Gerrit](https://gerrit-review.googlesource.com/Documentation/) for this
	purpose.

	### Register with Gerrit

	Before you can request code reviews, you need to register with Gerrit first. You
	can do that by going to <https://cos-review.googlesource.com> and clicking "Sign
	in" at the top right corner.

	### Set up git cookies

	You will also need to generate and configure your git cookies in order to push
	changes to Gerrit. The following steps help you with that:

	1. Go to https://cos-review.googlesource.com/new-password
	1. Log in with your google account
	1. Follow the on-screen directions page to set up/append to your
	`~/.gitcookies` file
	1. Verify that your cookies are correctly setup:

	```
	git ls-remote https://cos.googlesource.com/cos/tools.git
	```

	### Upload a CL

	```
	git push origin HEAD:refs/for/master
	```

	The command will print a URL to the CL that has just been uploaded. You can
	follow the URL to the Gerrit UI and add reviewers from there.

	## Community guidelines

	This project follows
	[Google's Open Source Community Guidelines](https://opensource.google/conduct/).