blob: af92d8482e7b6c1a9edce325911d273b360cd846 [file] [log] [blame] [view]
Contributing to OpenWeave
========================
Want to contribute? Great! First, read this page (including the small
print at the end).
## Bugs
If you find a bug in the source code, you can help us by [submitting a GitHub Issue](https://github.com/openweave/openweave-core/issues/new). The best bug reports provide a detailed description of the issue and step-by-step instructions for predictably reproducing the issue. Even better, you can [submit a Pull Request](#submitting-a-pull-request) with a fix.
## New Features
You can request a new feature by [submitting a GitHub Issue](https://github.com/openweave/openweave-core/issues/new).
If you would like to implement a new feature, please consider the scope of the new feature:
* *Large feature*: first [submit a GitHub
Issue](https://github.com/openweave/openweave-core/issues/new) and communicate
your proposal so that the community can review and provide feedback. Getting
early feedback will help ensure your implementation work is accepted by the
community. This will also allow us to better coordinate our efforts and
minimize duplicated effort.
* *Small feature*: can be implemented and directly [submitted as a Pull
Request](#submitting-a-pull-request).
## Contributing Code
The OpenWeave-Core follows the "Fork-and-Pull" model for accepting contributions.
### Initial Setup
Setup your GitHub fork and continuous-integration services:
1. Fork the [OpenWeave-Core
repository](https://github.com/openweave/openweave-core) by clicking "Fork"
on the web UI.
2. Enable [Travis CI](https://travis-ci.org/) by logging in with your GitHub
account and enabling your newly created fork. We use Travis CI for
Linux-based continuous integration checks. All contributions must pass these
checks to be accepted.
Setup your local development environment:
```bash
# Clone your fork
git clone git@github.com:<username>/openweave-core.git
# Configure upstream alias
git remote add upstream git@github.com:openweave/openweave-core.git
```
### Before you contribute
Before we can use your code, you must sign the [Google Individual
Contributor License Agreement][CLA-INDI] (CLA), which you can do
online. The CLA is necessary mainly because you own the copyright to
your changes, even after your contribution becomes part of our
codebase, so we need your permission to use and distribute your code.
We also need to be sure of various other thingsfor instance that
you'll tell us if you know that your code infringes on other people's
patents. You don't have to sign the CLA until after you've submitted
your code for review and a member has approved it, but you must do it
before we can put your code into our codebase. Before you start
working on a larger contribution, you should get in touch with us
first through the issue tracker with your idea so that we can help out
and possibly guide you. Coordinating up front makes it much easier to
avoid frustration later on.
[CLA-INDI]: https://cla.developers.google.com/about/google-individual
### Submitting a Pull Request
#### Branch
For each new feature, create a working branch:
```bash
# Create a working branch for your new feature
git branch --track <branch-name> origin/master
# Checkout the branch
git checkout <branch-name>
```
#### Create Commits
```bash
# Add each modified file you'd like to include in the commit
git add <file1> <file2>
# Create a commit
git commit
```
This will open up a text editor where you can craft your commit message.
#### Upstream Sync and Clean Up
Prior to submitting your pull request, you might want to do a few things to
clean up your branch and make it as simple as possible for the original
repository's maintainer to test, accept, and merge your work.
If any commits have been made to the upstream master branch, you should rebase
your development branch so that merging it will be a simple fast-forward that
won't require any conflict resolution work.
```bash
# Fetch upstream master and merge with your repository's master branch
git checkout master
git pull upstream master
# If there were any new commits, rebase your development branch
git checkout <branch-name>
git rebase master
```
Now, it may be desirable to squash some of your smaller commits down into a
small number of larger more cohesive commits. You can do this with an
interactive rebase:
```bash
# Rebase all commits on your development branch
git checkout
git rebase -i master
```
This will open up a text editor where you can specify which commits to squash.
#### Coding Conventions and Style
OpenWeave Core runs a style check on every pull request as part of the
continuous integration and pull request validation. In order to validate that
the submitted code meets the guidelines, you may run:
```bash
make -f Makefile-Standalone pretty-check
```
If you wish to use automated formatting tools, we have provided a `clang-format`
style. In order to automatically format the file, you'd run:
```bash
clang-format -i -style=file <src-filename>
```
#### Push and Test
```bash
# Checkout your branch
git checkout <branch-name>
# Push to your GitHub fork:
git push origin <branch-name>
```
This will trigger the Travis CI continuous-integration checks. You
can view the results in the respective services. Note that the integration
checks will report failures on occasion. If a failure occurs, you may try
rerunning the test via the Travis web UI.
#### Submit Pull Request
Once you've validated the Travis CI results, go to the page for
your fork on GitHub, select your development branch, and click the pull request
button. If you need to make any adjustments to your pull request, just push the
updates to GitHub. Your pull request will automatically track the changes on
your development branch and update.
#### Code reviews
All submissions, including submissions by project members, require review.
### Documentation
Documentation undergoes the same review process as code and
contributions may be mirrored on our [openweave.io][ow-io] website.
See the [Documentation Style Guide][doc-style] for more information on
how to author and format documentation for contribution.
### The small print
Contributions made by corporations are covered by a different
agreement than the one above, the [Software Grant and Corporate
Contributor License Agreement][CLA-CORP].
[CLA-CORP]: https://cla.developers.google.com/about/google-corporate
[doc-style]: /doc/STYLE_GUIDE.md
[ow-io]: https://openweave.io