Want to contribute? Great! First, read this page (including the small print at the end).
If you find a bug in the source code, you can help us by submitting a GitHub Issue. 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 with a fix.
You can request a new feature by submitting a GitHub Issue.
If you would like to implement a new feature, please consider the scope of the new feature:
Large feature: first submit a GitHub Issue 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.
The OpenWeave-Core follows the “Fork-and-Pull” model for accepting contributions.
Setup your GitHub fork and continuous-integration services:
Fork the OpenWeave-Core repository by clicking “Fork” on the web UI.
Enable Travis CI 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:
# 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 we can use your code, you must sign the Google Individual Contributor License Agreement (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 things—for 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.
For each new feature, create a working branch:
# Create a working branch for your new feature git branch --track <branch-name> origin/master # Checkout the branch git checkout <branch-name>
# 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.
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.
# 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:
# 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.
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:
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:
clang-format -i -style=file <src-filename>
# 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.
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.
All submissions, including submissions by project members, require review.
Documentation undergoes the same review process as code and contributions may be mirrored on our openweave.io website. See the Documentation Style Guide for more information on how to author and format documentation for contribution.
Contributions made by corporations are covered by a different agreement than the one above, the Software Grant and Corporate Contributor License Agreement.