1# Contributing
2
31. **Please sign one of the contributor license agreements below!**
41. Fork the repo, develop and test your code changes, add docs.
51. Make sure that your commit messages clearly describe the changes.
61. Send a pull request.
7
8## Table of contents
9* [Opening an issue](#opening-an-issue)
10* [How to run tests](#how-to-run-tests)
11* [Contributor License Agreements](#contributor-license-agreements)
12* [Contributor Code of Conduct](#contributor-code-of-conduct)
13
14## Opening an issue
15
16If you find a bug in the proxy code or an inaccuracy in the documentation,
17please open an issue. GitHub provides a guide, [Mastering
18Issues](https://guides.github.com/features/issues/), that is useful if you are
19unfamiliar with the process. Here are the specific steps for opening an issue:
20
211. Go to the project issues page on GitHub.
221. Click the green `New Issue` button located in the upper right corner.
231. In the title field, write a single phrase that identifies your issue.
241. In the main editor, describe your issue.
251. Click the submit button.
26
27Thank you. We will do our best to triage your issue within one business day, and
28attempt to categorize your issues with an estimate of the priority and issue
29type. We will try to respond with regular updates based on its priority:
30
31* **Critical** respond and update daily, resolve with a week
32* **High** respond and update weekly, resolve within six weeks
33* **Medium** respond and update every three months, best effort resolution
34* **Low** respond and update every six months, best effort resolution
35
36The priority we assign will be roughly a function of the number of users we
37expect to be impacted, as well as its severity. As a rule of thumb:
38
39<table>
40 <thead>
41 <tr>
42 <th rowspan="2">Severity</th>
43 <th colspan="4">Number of users</th>
44 </tr>
45 <tr>
46 <th>Handful</th>
47 <th>Some</th>
48 <th>Most</th>
49 <th>All</th>
50 </tr>
51 </thead>
52 <tr>
53 <td>Easy, obvious workaround</td>
54 <td>Low</td>
55 <td>Low</td>
56 <td>Medium</td>
57 <td>High
58 </tr>
59 <tr>
60<td>Non-obvious workaround available</td>
61<td>Low</td>
62<td>Medium</td>
63<td>High</td>
64<td>Critical</td>
65 </tr>
66
67 <tr>
68<td>Functionality blocked</td>
69<td>High</td>
70<td>High</td>
71<td>Critical</td>
72<td>Critical</td>
73 </tr>
74</table>
75
76## How to run tests
77
78The test suite includes both unit and integration tests. For macOS and Linux,
79there is a depenency on [FUSE][] that must be present on the system.
80
81### Test Dependencies
82
83When running tests on macOS and Linux, users will need to first install
84[FUSE][]. Windows users may skip this step.
85
86On Debian, use:
87
88```
89sudo apt-get install fuse
90```
91
92On macOS, use:
93
94```
95brew install --cask macfuse
96```
97
98### How to run just unit tests
99
100```
101go test -short ./...
102```
103
104### How to run all tests
105
106To run all integration tests, users will need a Google Cloud project with a
107MySQL, PostgreSQL, and SQL Server database, in addition to installing FUSE
108support. Note: Pull Requests will run these tests and as a result may be skipped
109locally if necessary.
110
111A sample `.envrc.example` file is included in the root directory which documents
112which environment variables must be set to run the integration tests. Copy this
113example file to `.envrc` at the root of the project, supply all the correct
114values for each variable, source the file (`source .envrc`, or consider using
115[direnv][]), and then run:
116
117```
118go test ./...
119```
120
121## Contributor License Agreements
122
123Open-source software licensing is a wonderful arrangement that benefits
124everyone, but in an imperfect world, we all need to exercise some legal
125prudence. In order to protect you, Google, and most of all, everyone who comes
126to depend on these libraries, we require that all contributors sign our short
127and human-readable Contributor License Agreement (CLA). We don't want to open
128the door to patent trolls, predatory lawyers, or anyone else who isn't on board
129with creating value and making the world a better place. We hope you will agree
130that the CLA offers very important protection and is easy to understand. Take a
131moment to read it carefully, and if you agree with what you read, please sign it
132now. If you believe you've already signed the appropriate CLA already for this
133or any other Google open-source project, you shouldn't have to do so again. You
134can review your signed CLAs at
135[cla.developers.google.com/clas](https://cla.developers.google.com/clas).
136
137First, check that you are signed in to a [Google
138Account](https://accounts.google.com) that matches your [local Git email
139address](https://help.github.com/articles/setting-your-email-in-git/). Then
140choose one of the following:
141
142* If you are **an individual writing original source code** and **you own the
143 intellectual property**, sign the [Individual
144 CLA](https://developers.google.com/open-source/cla/individual).
145* If you work for **a company that wants to allow you to contribute**, sign the
146 [Corporate CLA](https://developers.google.com/open-source/cla/corporate).
147
148You (and your authorized signer, if corporate) can sign the CLA
149electronically. After that, we'll be able to accept your contributions.
150
151## Contributor Code of Conduct
152
153As contributors and maintainers of this project, and in the interest of
154fostering an open and welcoming community, we pledge to respect all people who
155contribute through reporting issues, posting feature requests, updating
156documentation, submitting pull requests or patches, and other activities.
157
158We are committed to making participation in this project a harassment-free
159experience for everyone, regardless of level of experience, gender, gender
160identity and expression, sexual orientation, disability, personal appearance,
161body size, race, ethnicity, age, religion, or nationality.
162
163Examples of unacceptable behavior by participants include:
164
165* The use of sexualized language or imagery
166* Personal attacks
167* Trolling or insulting/derogatory comments
168* Public or private harassment
169* Publishing other's private information, such as physical or electronic
170addresses, without explicit permission
171* Other unethical or unprofessional conduct.
172
173Project maintainers have the right and responsibility to remove, edit, or reject
174comments, commits, code, wiki edits, issues, and other contributions that are
175not aligned to this Code of Conduct. By adopting this Code of Conduct, project
176maintainers commit themselves to fairly and consistently applying these
177principles to every aspect of managing this project. Project maintainers who do
178not follow or enforce the Code of Conduct may be permanently removed from the
179project team.
180
181This code of conduct applies both within project spaces and in public spaces
182when an individual is representing the project or its community.
183
184Instances of abusive, harassing, or otherwise unacceptable behavior may be
185reported by opening an issue or contacting one or more of the project
186maintainers.
187
188This Code of Conduct is adapted from the [Contributor
189Covenant](http://contributor-covenant.org), version 1.2.0, available at
190[http://contributor-covenant.org/version/1/2/0/](http://contributor-covenant.org/version/1/2/0/)
191
192[FUSE]: https://www.kernel.org/doc/html/latest/filesystems/fuse.html
193[direnv]: https://direnv.net/
View as plain text