espressif/openthread
1
0
Fork 0
mirror of https://github.com/espressif/openthread.git synced 2025-08-06 14:52:18 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update CONTRIBUTING.md (#1546)

Browse Source
This commit is contained in:
Jonathan Hui
2017-04-04 09:20:58 -07:00
committed by GitHub
parent 5e34eee014
commit af775eca9a
1 changed files with 136 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
CONTRIBUTING.md
View File

@ -1,37 +1,142 @@
Want to contribute? Great! First, read this page (including the small print at the end).
# Contributing to OpenThread
### Before you contribute
Before we can use your code, you must sign the
[Google Individual Contributor License Agreement]
(https://cla.developers.google.com/about/google-individual)
(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.
We would love for you to contribute to OpenThread and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow.
### Code reviews
All submissions, including submissions by project members, require review. We
use Github pull requests for this purpose.
* [1 Code of Conduct](#code-of-conduct)
* [2 Bugs](#bugs)
* [3 New Features](#new-features)
* [4 Contributing Code](#contributing-code)
* [4.1 Initial Setup](#initial-setup)
* [4.2 Contributor License Agreement (CLA)](#contributor-license-agreement--cla-)
* [4.3 Submitting a Pull Request](#submitting-a-pull-request)
### Code style
Before submitting a pull request make sure to run:
## Code of Conduct
make pretty
This will format the source code according to the OpenThread code style. This
command requires the `astyle` tool. Please refer to your operating system
documentation to find information on how to install `astyle`.
Help us keep OpenThread open and inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
### 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]
(https://cla.developers.google.com/about/google-corporate).
## Bugs
If you find a bug in the source code, you can help us by [submitting a GitHub Issue](https://github.com/openthread/openthread/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/openthread/openthread/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/openthread/openthread/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 OpenThread Project follows the "Fork-and-Pull" model for accepting contributions.
### Initial Setup
Setup your GitHub fork and continuous-integration services:
1. Fork the [OpenThread repository](https://github.com/openthread/openthread) by clicking "Fork" on the web UI.
2. Enable [Travis CI](https://travis-ci.org/) and [AppVeyor](https://ci.appveyor.com/) by logging in the respective services with your GitHub account and enabling your newly created fork. We use Travis CI for Linux-based continuous integration checks and AppVeyor for Windows-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>/openthread.git
# Configure upstream alias
git remote add upstream git@github.com:openthread/openthread.git
```
### Contributor License Agreement (CLA)
The OpenThread Project requires all contributors to sign a Contributor License Agreement ([individual](https://developers.google.com/open-source/cla/individual) or [corporate](https://developers.google.com/open-source/cla/corporate)) in order to protect contributors, users, and Google in issues of intellectual property.
With each Pull Request, an automated check occurs to verify that you have signed the CLA. Make sure that you sign the CLA with the same email address associated with your commits (i.e. via the `user.email` Git config as described on GitHub's [Set up Git](https://help.github.com/articles/set-up-git/) page.
NOTE: Only original source code from you and other people that have signed the CLA can be accepted into the repository. This policy does not apply to [third_party](https://github.com/openthread/openthread/tree/master/third_party).
### 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 repo'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 repo'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
OpenThread uses and enforces the [OpenThread Coding Conventions and Style](STYLE_GUIDE.md) on all code, except for code located in [third_party](third_party).
As part of the cleanup process, you should also run `make pretty-check` to ensure that your code passes the baseline code style checks.
```bash
./bootstrap
./configure --enable-ftd --enable-cli --enable-diag --enable-dhcp6-client --enable-dhcp6-server --enable-commissioner --enable-joiner --with-examples=posix
make pretty-check
```
Make sure to include any code format changes in your commits.
#### 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 and AppVeyor 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 and/or AppVeyor web UI.
#### Submit Pull Request
Once you've validated the Travis CI and AppVeyor 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.