| # 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 |