error-prone-support/CONTRIBUTING.md

# Contributing

Thank you for checking this document! This project is free software, and we
(the maintainers) encourage and value any contribution.

Here are some guidelines to help you get started.

## 🐛 Reporting a bug

Like any non-trivial piece of software, this library is probably not bug-free.
If you found a bug, feel free to [report the issue][error-prone-support-issues]
on GitHub.

Before doing so, please:
- Verify that the issue is reproducible against the latest version of the
  project.
- Search through the existing set of issues to see whether the problem is
  already known. With some luck a solution is already in place, or a workaround
  may have been provided.

When filing a bug report, please include the following:
- Any relevant information about your environment. This should generally
  include the output of `java --version`, as well as the version of Error Prone
  you're using.
- A description of what is going on (e.g. logging output, stacktraces).
- A minimum reproducible example, so that other developers can try to reproduce
  (and optionally fix) the bug.
- Any additional information that may be relevant.

## 💡 Reporting an improvement

If you would like to see an improvement, you can file a [GitHub
issue][error-prone-support-issues]. This is also a good idea when you're
already working towards opening a pull request, as this allows for discussion
around the idea.

## 🚀 Opening a pull request

All submissions, including submissions by project members, require approval by
at least two reviewers. We use [GitHub pull
requests][error-prone-support-pulls] for this purpose.

Before opening a pull request, please check whether there are any existing
(open or closed) issues or pull requests addressing the same problem. This
avoids double work or lots of time spent on a solution that may ultimately not
be accepted. When in doubt, make sure to first raise an
[issue][error-prone-support-issues] to discuss the idea.

To the extent possible, the pull request process guards our coding guidelines.
Some pointers:
- Try to make sure that the
  [`./run-full-build.sh`][error-prone-support-full-build] script completes
  successfully, ideally before opening a pull request. See the [development
  instructions][error-prone-support-developing] for details on how to
  efficiently resolve many of the errors and warnings that may be reported. (In
  particular, make sure to run `mvn fmt:format` and
  [`./apply-error-prone-suggestions.sh`][error-prone-support-patch].) That
  said, if you feel that the build fails for invalid or debatable reasons, or
  if you're unsure how to best resolve an issue, don't let that discourage you
  from opening a PR with a failing build; we can have a look at the issue
  together!
- Checks should be _topical_: ideally they address a single concern.
- Where possible checks should provide _fixes_, and ideally these are
  completely behavior-preserving. In order for a check to be adopted by users
  it must not "get in the way". So for a check that addresses a relatively
  trivial stylistic concern it is doubly important that the violations it
  detects can be auto-patched.
- Make sure you have read Error Prone's [criteria for new
  checks][error-prone-criteria]. Most guidelines described there apply to this
  project as well, except that this project _does_ focus quite heavy on style
  enforcement. But that just makes the previous point doubly important.
- Make sure that a check's [(mutation) test
  coverage][error-prone-support-mutation-tests] is or remains about as high as
  it can be. Not only does this lead to better tests, it also points out
  opportunities to simplify the code.
- Please restrict the scope of a pull request to a single feature or fix. Don't
  sneak in unrelated changes; instead just open more than one pull request 😉.

[error-prone-criteria]: https://errorprone.info/docs/criteria
[error-prone-support-developing]: https://github.com/PicnicSupermarket/error-prone-support/tree/master#-developing-error-prone-support
[error-prone-support-full-build]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-full-build.sh
[error-prone-support-issues]: https://github.com/PicnicSupermarket/error-prone-support/issues
[error-prone-support-mutation-tests]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/run-branch-mutation-tests.sh
[error-prone-support-patch]: https://github.com/PicnicSupermarket/error-prone-support/blob/master/apply-error-prone-suggestions.sh
[error-prone-support-pulls]: https://github.com/PicnicSupermarket/error-prone-support/pulls