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/).