Thank you for your interest in contributing to gcloud. The APIs of the Google Cloud Platform constitute a huge offering that continues to expand at a rapid pace. Because there is so much work to do to make the gcloud libraries the best-ever way to access these APIs, we desperately need your help. Your contributions are more than just welcome, they are essential.
Therefore, out of respect for your time and effort, we are trying hard to make contributing to gcloud a safe, efficient, and well-defined process. If you encounter any difficulty during the process, do not hesitate to get in touch.
Open-source software licensing is a wonderful arrangement that benefits everyone, but in an imperfect world, we all need to exercise some legal prudence. In order to protect you, Google, and most of all, everyone who comes to depend on these libraries, we require that all contributors sign our short and human-readable Contributor License Agreement (CLA). We don't want to open the door to patent trolls, predatory lawyers, or anyone else who isn't on board with creating value and making the world a better place. We hope you will agree that the CLA offers very important protection and is easy to understand. Take a moment to read it carefully, and if you agree with what you read, please sign it now. If you believe you've already signed the appropriate CLA already for this or any other Google open-source project, you shouldn't have to do so again. You can review your signed CLAs at cla.developers.google.com/clas.
First, check that you are signed in to a Google Account that matches your local Git email address. Then choose one of the following:
- If you are an individual writing original source code and you own the intellectual property, sign the Individual CLA.
- If you work for a company that wants to allow you to contribute, sign the Corporate CLA.
You (and your authorized signer, if corporate) can sign the CLA electronically. After that, we'll be able to accept your contributions.
If you've tried everything in our Troubleshooting guide and are still running into problems, it is probably time to open a GitHub issue. GitHub provides a guide, Mastering Issues, that is useful if you are unfamiliar with the process. Here are the specific steps for opening a gcloud issue:
- Go to the project issues page on GitHub.
- Click the green
New Issuebutton located in the upper right corner. - In the title field, write a single phrase that identifies your issue, including service, class, and method names if appropriate.
- In the main editor, describe your issue. The details of your description will vary depending on your issue type, as follows:
bug- Document the steps to reproduce. List relevant details about your environment, especially your Ruby version. Include the full stack trace (backtrace) if there is an exception.enhancement- Put on your salesman hat and sell your proposed feature. If you can, link to some compelling external examples.docs- Helping us improve the project documentation should not be a hassle. Just quickly let us know where the problem is, and jot down a suggestion or two for making things better.
- Click the submit button.
Thank you. We will do our best to comment on your issue within one business day.
The GitHub project issues page is the place to look for shovel-ready work. Here are some suggestions for your first contribution, listed in ascending order of effort and difficulty.
- Confirm a
bugissue by reproducing it in your own environment and adding a comment detailing what you found. - Review a pull request by checking out the creator's branch, and examining the change in your own environment.
- Offer to work on a
docsissue. - Offer to work on a
bugissue.
If you can't find anything actionable, be sure to check back again in a week or so.
The following is a high-level overview of how to contribute to a gcloud client library:
-
Open an issue to ensure that your work is coordinated with the efforts of others.
-
Sign the Contributor License Agreement (CLA).
-
Clone the project repository from GitHub.
$ git clone git@github.com:GoogleCloudPlatform/<project-name>.git-
Set up your local development environment.
-
Run the project tests. You need to be certain that all tests are passing in your local environment before you make any changes.
-
Create a new local branch.
$ git checkout -b <new-issue-name>-
Make changes. Be sure to edit or add API documentation for your changes.
-
Edit or add tests. All contributions must include tests that ensure the contributed code behaves as expected. (You did this in the previous step? Congrats, you just scored the TDD badge.)
-
Check your coding style. Please follow the style guide for the library.
-
Run the tests again.
-
Commit your code. Take a moment to write a good commit message. If you end up with several commits for one logical change, squash these commits for clarity.
-
On GitHub, create a fork of the project.
-
Add your fork as a remote to your local repository:
$ git remote add <your-username> git@github.com:<your-username>/<project-name>.git- Push your branch to your fork.
$ git push <your-username> <new-issue-name>- On the GitHub page for your fork and branch, create a pull request by clicking
Compare & pull request. Edit the message copied from your commit, adding more detail if needed, then clickCreate pull request.
Your pull request is where we (and anyone else who is interested) will discuss your change.
Be sure to check your pull request for a cla:yes label. If you see a cla:no label, verify that you have signed the CLA using a Google Account that matches your Git email. Once your pull request has the cla:yes label, look out for an email notification that either your pull request has been merged, or someone has requested a little more work on it. If more work is needed, repeat steps 5, 7-11, and 14. Then, let us know when you're done and we'll take another look.
Happy contributing! And, once again, thank you.