# How to Contribute

We'd love to accept your patches and contributions to this project. There are
just a few small guidelines you need to follow.

## Communciation

Communication will help your concept reach consensus before getting to code, and
potentially conserve time and effort.

*   Join the developer's mailing list: verible-dev@googlegroups.com
    ([join](https://groups.google.com/forum/#!forum/verible-dev/join))
*   Use the github issue tracker to discuss and comment on specific issues. We
    use the assignment status to signal who is working on what. Ask to be
    assigned to an issue if you'd like to volunteer, and un-assign yourself if
    you find yourself unavailable.

## Contributor License Agreement

Contributions to this project must be accompanied by a 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.

You generally only need to submit a CLA once, so if you've already submitted one
(even if it was for a different project), you probably don't need to do it
again.

## Code reviews

All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.

### Style

Our C++ code mostly follows [Google's C++ style guide][google-cpp-style].

On a pull request, the Continuous Integration (CI) will verify this style, so
to make this smooth, run `clang-format` on your modified files before submitting
a pull request:

```
clang-format --style=file -i <your-modified-c++-files>
```

There is a script that runs build cleaning, formatting, clang-tidy and
tests in one go:

```
.github/bin/before-submit.sh
```

### Testing

Testing is a critical component to any code contribution. Make sure your the
changes you introduce come with test code to protect against future regression.
Prefer unit-tests in most cases, and end-to-end tests in others. We also welcome
contributions that contain _only_ test cases (where no code change is needed)!

We encourage you to start on any open issue by proposing test cases for
discussion before diving into any implementation. Where applicable, also
consider _negative_ tests. Try to keep the majority of tests small and focused.

#### Running Code Coverage

Coverage is a useful tool to find branches that are never exercised in any
test, so make sure tests for new features exercise all possible branches.

To inspect coverage locally, run

```
MODE=coverage .github/bin/build-and-test.sh
.github/bin/generate-coverage-html.sh
```

The coverage report can then be found in `coverage-html/index.html`

## Community Guidelines

This project follows
[Google's Open Source Community Guidelines](https://opensource.google/conduct/).

<!-- reference links -->

[google-cpp-style]: https://google.github.io/styleguide/cppguide.html
[codecov]: https://app.codecov.io/gh/chipsalliance/verible