153 lines
7.2 KiB
Markdown
153 lines
7.2 KiB
Markdown
# How to Contribute
|
|
|
|
We would love to accept your patches and contributions to this project. Here is
|
|
how you can help.
|
|
|
|
## Filing issues
|
|
|
|
Filing issues is an important way you can contribute to the Wire Project. We
|
|
want your feedback on things like bugs, desired API changes, or just anything
|
|
that isn't working for you.
|
|
|
|
### Bugs
|
|
|
|
If your issue is a bug, open one
|
|
[here](https://github.com/google/wire/issues/new). The easiest way to file an
|
|
issue with all the right information is to run `go bug`. `go bug` will print out
|
|
a handy template of questions and system information that will help us get to
|
|
the root of the issue quicker.
|
|
|
|
### Changes
|
|
|
|
Unlike the core Go project, we do not have a formal proposal process for
|
|
changes. If you have a change you would like to see in Wire, please file an
|
|
issue with the necessary details.
|
|
|
|
### Triaging
|
|
|
|
The Go Cloud team triages issues at least every two weeks, but usually within
|
|
two business days. Bugs or feature requests are either placed into a **Sprint**
|
|
milestone which means the issue is intended to be worked on. Issues that we
|
|
would like to address but do not have time for are placed into the [Unplanned][]
|
|
milestone.
|
|
|
|
[Unplanned]: https://github.com/google/wire/milestone/1
|
|
|
|
## Contributing Code
|
|
|
|
We love accepting contributions! If your change is minor, please feel free
|
|
submit a [pull request](https://help.github.com/articles/about-pull-requests/).
|
|
If your change is larger, or adds a feature, please file an issue beforehand so
|
|
that we can discuss the change. You're welcome to file an implementation pull
|
|
request immediately as well, although we generally lean towards discussing the
|
|
change and then reviewing the implementation separately.
|
|
|
|
### Finding something to work on
|
|
|
|
If you want to write some code, but don't know where to start or what you might
|
|
want to do, take a look at our [Unplanned][] milestone. This is where you can
|
|
find issues we would like to address but can't currently find time for. See if
|
|
any of the latest ones look interesting! If you need help before you can start
|
|
work, you can comment on the issue and we will try to help as best we can.
|
|
|
|
### Contributor License Agreement
|
|
|
|
Contributions to this project can only be made by those who have signed Google's
|
|
Contributor License Agreement. 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.
|
|
|
|
As a personal contributor, you only need to sign the Google CLA once across all
|
|
Google projects. If you've already signed the CLA, there is no need to do it
|
|
again. If you are submitting code on behalf of your employer, there's
|
|
[a separate corporate CLA that your employer manages for you](https://opensource.google.com/docs/cla/#external-contributors).
|
|
|
|
## Making a pull request
|
|
|
|
* Follow the normal
|
|
[pull request flow](https://help.github.com/articles/creating-a-pull-request/)
|
|
* Build your changes using Go 1.11 with Go modules enabled. Wire's continuous
|
|
integration uses Go modules in order to ensure
|
|
[reproducible builds](https://research.swtch.com/vgo-repro).
|
|
* Test your changes using `go test ./...`. Please add tests that show the
|
|
change does what it says it does, even if there wasn't a test in the first
|
|
place.
|
|
* Feel free to make as many commits as you want; we will squash them all into
|
|
a single commit before merging your change.
|
|
* Check the diffs, write a useful description (including something like
|
|
`Fixes #123` if it's fixing a bug) and send the PR out.
|
|
* [Travis CI](http://travis-ci.com) will run tests against the PR. This should
|
|
happen within 10 minutes or so. If a test fails, go back to the coding stage
|
|
and try to fix the test and push the same branch again. You won't need to
|
|
make a new pull request, the changes will be rolled directly into the PR you
|
|
already opened. Wait for Travis again. There is no need to assign a reviewer
|
|
to the PR, the project team will assign someone for review during the
|
|
standard [triage](#triaging) process.
|
|
|
|
## Code review
|
|
|
|
All submissions, including submissions by project members, require review. It is
|
|
almost never the case that a pull request is accepted without some changes
|
|
requested, so please do not be offended!
|
|
|
|
When you have finished making requested changes to your pull request, please
|
|
make a comment containing "PTAL" (Please Take Another Look) on your pull
|
|
request. GitHub notifications can be noisy, and it is unfortunately easy for
|
|
things to be lost in the shuffle.
|
|
|
|
Once your PR is approved (hooray!) the reviewer will squash your commits into a
|
|
single commit, and then merge the commit onto the Wire master branch. Thank you!
|
|
|
|
## Github code review workflow conventions
|
|
|
|
(For project members and frequent contributors.)
|
|
|
|
As a contributor:
|
|
|
|
- Try hard to make each Pull Request as small and focused as possible. In
|
|
particular, this means that if a reviewer asks you to do something that is
|
|
beyond the scope of the Pull Request, the best practice is to file another
|
|
issue and reference it from the Pull Request rather than just adding more
|
|
commits to the existing PR.
|
|
- Adding someone as a Reviewer means "please feel free to look and comment";
|
|
the review is optional. Choose as many Reviewers as you'd like.
|
|
- Adding someone as an Assignee means that the Pull Request should not be
|
|
submitted until they approve. If you choose multiple Assignees, wait until
|
|
all of them approve. It is fine to ask someone if they are OK with being
|
|
removed as an Assignee.
|
|
- Note that if you don't select any assignees, ContributeBot will turn all
|
|
of your Reviewers into Assignees.
|
|
- Make as many commits as you want locally, but try not to push them to Github
|
|
until you've addressed comments; this allows the email notification about
|
|
the push to be a signal to reviewers that the PR is ready to be looked at
|
|
again.
|
|
- When there may be confusion about what should happen next for a PR, be
|
|
explicit; add a "PTAL" comment if it is ready for review again, or a "Please
|
|
hold off on reviewing for now" if you are still working on addressing
|
|
comments.
|
|
- "Resolve" comments that you are sure you've addressed; let your reviewers
|
|
resolve ones that you're not sure about.
|
|
- Do not use `git push --force`; this can cause comments from your reviewers
|
|
that are associated with a specific commit to be lost. This implies that
|
|
once you've sent a Pull Request, you should use `git merge` instead of `git
|
|
rebase` to incorporate commits from the master branch.
|
|
|
|
As a reviewer:
|
|
|
|
- Be timely in your review process, especially if you are an Assignee.
|
|
- Try to use `Start a Review` instead of single comments, to reduce email
|
|
spam.
|
|
- "Resolve" your own comments if they have been addressed.
|
|
- If you want your review to be blocking, and are not currently an Assignee,
|
|
add yourself as an Assignee.
|
|
|
|
When squashing-and-merging:
|
|
|
|
- Ensure that **all** of the Assignees have approved.
|
|
- Do a final review of the one-line PR summary, ensuring that it accurately
|
|
describes the change.
|
|
- Delete the automatically added commit lines; these are generally not
|
|
interesting and make commit history harder to read.
|