CONTRIBUTING.md - third_party/openweave-core - Git at Google

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

 [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
	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 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.

	[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