github.com/yorinasub17/go-cloud@v0.27.40/CONTRIBUTING.md (about) 1 # How to Contribute 2 3 We would love to accept your patches and contributions to this project. Here is 4 how you can help. 5 6 ## Filing issues 7 8 Filing issues is an important way you can contribute to the Go Cloud Development 9 Kit. We want your feedback on things like bugs, desired API changes, or just 10 anything that isn't working for you. 11 12 ### Bugs 13 14 If your issue is a bug, open one 15 [here](https://github.com/google/go-cloud/issues/new). The easiest way to file 16 an issue with all the right information is to run `go bug`. `go bug` will print 17 out a handy template of questions and system information that will help us get 18 to the root of the issue quicker. Please start the title of your bug with the 19 name of the affected package, followed by a colon, followed by a short summary 20 of the issue, like "blob/gcsblob: not blobby enough". 21 22 ### Changes 23 24 Unlike the core Go project, we do not have a formal proposal process for 25 changes. If you have a change you would like to see in the Go CDK, please file 26 an issue with the necessary details. 27 28 ### Triaging 29 30 The Go CDK team triages issues at least every two weeks, but usually within two 31 business days. Issues that we would like to address, but do not have time for 32 are placed into the [Unplanned][] milestone. 33 34 [Unplanned]: https://github.com/google/go-cloud/milestone/2 35 36 ## Contributing Code 37 38 We love accepting contributions! If your change is minor, please feel free 39 to submit a [pull request](https://help.github.com/articles/about-pull-requests/). 40 If your change is larger, or adds a feature, please file an issue beforehand so 41 that we can discuss the change. You're welcome to file an implementation pull 42 request immediately as well, although we generally lean towards discussing the 43 change and then reviewing the implementation separately. 44 45 Be sure to take a look at the [internal docs][], which include more information 46 about conventions and design patterns found in the project. 47 48 [internal docs]: internal/docs/README.md 49 50 ### Finding something to work on 51 52 If you want to write some code, but don't know where to start or what you might 53 want to do, take a look at the [Good First Issue] label and our [Unplanned][] 54 milestone. The latter is where you can find issues we would like to address, but 55 can't currently find time for. See if any of the latest ones look interesting! 56 If you need help before you can start work, you can comment on the issue, and we 57 will try to help as best we can. 58 59 [Good First Issue]: https://github.com/google/go-cloud/labels/good%20first%20issue 60 61 ### Contributor License Agreement 62 63 Contributions to this project can only be made by those who have signed Google's 64 Contributor License Agreement. You (or your employer) retain the copyright to 65 your contribution, so this simply gives us permission to use and redistribute your 66 contributions as part of the project. Head over to 67 <https://cla.developers.google.com/> to see your current agreements on file or 68 to sign a new one. 69 70 As a personal contributor, you only need to sign the Google CLA once across all 71 Google projects. If you've already signed the CLA, there is no need to do it 72 again. If you are submitting code on behalf of your employer, there's 73 [a separate corporate CLA that your employer manages for you](https://opensource.google.com/docs/cla/#external-contributors). 74 75 ### A Warning About Tests 76 77 Tests that interact with cloud providers are written using a replay method, 78 where the test is run and actually performs the operations, and the 79 requests/results of the operations are stored in a replay file. This replay file 80 is then read back in unit tests on Travis, so the tests get to operate with real 81 data. Unfortunately, while the Go CDK team can generate these replay files 82 against our test cloud infrastructure, it is not yet possible for external 83 contributors to do the same. We want to improve this process in the future and 84 are researching how we can do this. If you have any ideas, please 85 [file an issue](https://github.com/google/go-cloud/issues/new)! 86 87 #### Writing and running tests against a cloud environment 88 89 If you can create cloud resources, setup your authentication using either `aws` 90 or `gcloud` and set the default project as the test project. Most tests will 91 have constants defining the resource names they use (for example, for `blob` 92 tests, the bucket name); update the constant and then run `go test -record`. New 93 replay files will be generated. This uses API quota and will create and delete 94 cloud resources. Replay files scrub sensitive information. 95 [Send your PR](#making-a-pull-request) without the replay files, and we can 96 generate new ones to be used by others. 97 98 ### Dependencies 99 100 The Go CDK has a policy to depend only on code licensed under one of the 101 [`notice`][notice licenses], [`permissive`][permissive licenses], or 102 [`unencumbered`][unencumbered licenses] categories in the 103 [Google Open Source Licenses][] documentation. This is enforced with a 104 Travis build check that verifies that every dependency is in the 105 [`alldeps` file][]. Do not add new direct or indirect dependencies to the Go CDK 106 unless you have verified that the dependency is released under an acceptable 107 license. 108 109 [`alldeps` file]: https://github.com/google/go-cloud/blob/master/internal/testing/alldeps 110 [notice licenses]: https://opensource.google.com/docs/thirdparty/licenses/#notice 111 [permissive licenses]: https://opensource.google.com/docs/thirdparty/licenses/#permissive 112 [unencumbered licenses]: https://opensource.google.com/docs/thirdparty/licenses/#unencumbered 113 [Google Open Source Licenses]: https://opensource.google.com/docs/thirdparty/licenses/ 114 115 ## Making a pull request 116 117 * Follow the normal 118 [pull request flow](https://help.github.com/articles/creating-a-pull-request/). 119 * Build your changes using Go 1.11 with Go modules enabled. The Go CDK's 120 continuous integration uses Go modules in order to ensure 121 [reproducible builds](https://research.swtch.com/vgo-repro). 122 * Test your changes using `go test ./...`. Please add tests that show the 123 change does what it says it does, even if there wasn't a test in the first 124 place. Don't add the replay files to your commits. 125 * Feel free to make as many commits as you want; we will squash them all into 126 a single commit before merging your change. 127 * Check the diffs, write a useful description (including something like 128 `Fixes #123` if it's fixing a bug) and send the PR out. Please start the 129 title of your pull request with the name of the affected package, followed 130 by a colon, followed by a short summary of the change, like "blob/gcsblob: 131 add more tests". 132 * [Travis CI](http://travis-ci.com) will run tests against the PR. This should 133 happen within 10 minutes or so. If a test fails, go back to the coding stage 134 and try to fix the test and push the same branch again. You won't need to 135 make a new pull request, the changes will be rolled directly into the PR you 136 already opened. Wait for Travis again. There is no need to assign a reviewer 137 to the PR, the project team will assign someone for review during the 138 standard [triage](#triaging) process. 139 140 ## Code review 141 142 All submissions, including submissions by project members, require review. It is 143 almost never the case that a pull request is accepted without some changes 144 requested, so please do not be offended! 145 146 When you have finished making requested changes to your pull request, please 147 make a comment containing "PTAL" (Please Take Another Look) on your pull 148 request. GitHub notifications can be noisy, and it is unfortunately easy for 149 things to be lost in the shuffle. 150 151 Once your PR is approved (hooray!), the reviewer will squash your commits into a 152 single commit and then merge the commit onto the Go CDK master branch. Thank 153 you! 154 155 ## Github code review workflow conventions 156 157 (For project members and frequent contributors.) 158 159 As a contributor: 160 161 - Try hard to make each Pull Request as small and focused as possible. In 162 particular, this means that if a reviewer asks you to do something that is 163 beyond the scope of the Pull Request, the best practice is to file another 164 issue and reference it from the Pull Request rather than just adding more 165 commits to the existing PR. 166 - Adding someone as a Reviewer means "please feel free to look and comment"; 167 the review is optional. Choose as many Reviewers as you'd like. 168 - Adding someone as an Assignee means that the Pull Request should not be 169 submitted until they approve. If you choose multiple Assignees, wait until 170 all of them approve. It is fine to ask someone if they are OK with being 171 removed as an Assignee. 172 - Note that if you don't select any assignees, ContributeBot will turn all 173 of your Reviewers into Assignees. 174 - Make as many commits as you want locally, but try not to push them to Github 175 until you've addressed comments; this allows the email notification about 176 the push to be a signal to reviewers that the PR is ready to be looked at 177 again. 178 - When there may be confusion about what should happen next for a PR, be 179 explicit; add a "PTAL" comment if it is ready for review again, or a "Please 180 hold off on reviewing for now" if you are still working on addressing 181 comments. 182 - "Resolve" comments that you are sure you've addressed; let your reviewers 183 resolve ones that you're not sure about. 184 - Do not use `git push --force`; this can cause comments from your reviewers 185 that are associated with a specific commit to be lost. This implies that 186 once you've sent a Pull Request, you should use `git merge` instead of `git 187 rebase` to incorporate commits from the master branch. 188 - Travis checks will fail if you haven't run `gofmt -w -s`. 189 - Travis checks will fail if your PR has backwards-incompatible changes, 190 unless one of your commits has the strings `BREAKING_CHANGE_OK` in the first 191 line of the commit message. 192 193 As a reviewer: 194 195 - Be timely in your review process, especially if you are an Assignee. 196 - Try to use `Start a Review` instead of single comments, to reduce email 197 spam. 198 - "Resolve" your own comments if they have been addressed. 199 - If you want your review to be blocking, and are not currently an Assignee, 200 add yourself as an Assignee. 201 202 When squashing-and-merging: 203 204 - Ensure that **all** of the Assignees have approved. 205 - Do a final review of the one-line PR summary, ensuring that it meets the 206 guidelines (e.g., "blob: add more blobbing") and accurately describes the 207 change. 208 - Mark breaking changes with `BREAKING_CHANGE` in the commit message (e.g., 209 "blob: BREAKING_CHANGE remove old blob"). 210 - If the PR includes a breaking change, it will be declared via a commit 211 with `BREAKING_CHANGE_OK` in it (see Contributor section above). 212 - You can omit the marker if the change is technically breaking, but not 213 expected to affect users (e.g., it's a breaking change to an object that 214 wasn't in the last tagged release, or it's a change to a portable API 215 function that's only expected to be used by driver implementations). 216 - Delete the automatically added commit lines; these are generally not 217 interesting and make commit history harder to read.