third_party/ot-br-posix/repo/CONTRIBUTING.md

   1 # Contributing to OpenThread
   2
   3 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.
   4
   5 - [1 Code of Conduct](#code-of-conduct)
   6 - [2 Bugs](#bugs)
   7 - [3 New Features](#new-features)
   8 - [4 Contributing Code](#contributing-code)
   9   - [4.1 Initial Setup](#initial-setup)
  10   - [4.2 Contributor License Agreement (CLA)](#contributor-license-agreement--cla-)
  11   - [4.3 Submitting a Pull Request](#submitting-a-pull-request)
  12
  13 ## Code of Conduct
  14
  15 Help us keep OpenThread open and inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
  16
  17 ## Bugs
  18
  19 If you find a bug in the source code, you can help us by [submitting a GitHub Issue](https://github.com/openthread/ot-br-posix/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.
  20
  21 ## New Features
  22
  23 You can request a new feature by [submitting a GitHub Issue](https://github.com/openthread/ot-br-posix/issues/new).
  24
  25 If you would like to implement a new feature, please consider the scope of the new feature:
  26
  27 - _Large feature_: first [submit a GitHub Issue](https://github.com/openthread/ot-br-posix/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.
  28
  29 - _Small feature_: can be implemented and directly [submitted as a Pull Request](#submitting-a-pull-request).
  30
  31 ## Contributing Code
  32
  33 The OpenThread Project follows the "Fork-and-Pull" model for accepting contributions.
  34
  35 ### Initial Setup
  36
  37 Setup your GitHub fork and continuous-integration services:
  38
  39 1. Fork the [OpenThread repository](https://github.com/openthread/ot-br-posix) by clicking "Fork" on the web UI.
  40 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 and macOS continuous integration checks. All contributions must pass these checks to be accepted.
  41
  42 Setup your local development environment:
  43
  44 ```bash
  45 # Clone your fork
  46 git clone git@github.com:<username>/openthread.git
  47
  48 # Configure upstream alias
  49 git remote add upstream git@github.com:openthread/ot-br-posix.git
  50 ```
  51
  52 ### Contributor License Agreement (CLA)
  53
  54 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.
  55
  56 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.
  57
  58 ### Submitting a Pull Request
  59
  60 #### Branch
  61
  62 For each new feature, create a working branch:
  63
  64 ```bash
  65 # Create a working branch for your new feature
  66 git branch --track <branch-name> origin/master
  67
  68 # Checkout the branch
  69 git checkout <branch-name>
  70 ```
  71
  72 #### Create Commits
  73
  74 ```bash
  75 # Add each modified file you'd like to include in the commit
  76 git add <file1> <file2>
  77
  78 # Create a commit
  79 git commit
  80 ```
  81
  82 This will open up a text editor where you can craft your commit message.
  83
  84 #### Upstream Sync and Clean Up
  85
  86 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.
  87
  88 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.
  89
  90 ```bash
  91 # Fetch upstream master and merge with your repo's master branch
  92 git checkout master
  93 git pull upstream master
  94
  95 # If there were any new commits, rebase your development branch
  96 git checkout <branch-name>
  97 git rebase master
  98 ```
  99
 100 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:
 101
 102 ```bash
 103 # Rebase all commits on your development branch
 104 git checkout
 105 git rebase -i master
 106 ```
 107
 108 This will open up a text editor where you can specify which commits to squash.
 109
 110 #### Coding Conventions and Style
 111
 112 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). Use `script/make-pretty` and `script/make-pretty check` to automatically reformat code and check for code-style compliance, respectively. OpenThread currently requires [clang-format v9.0.0](https://releases.llvm.org/download.html#9.0.0) for C/C++ and [yapf](https://github.com/google/yapf) for Python.
 113
 114 As part of the cleanup process, you should also run `script/make-pretty check` to ensure that your code passes the baseline code style checks.
 115
 116 #### Push and Test
 117
 118 ```bash
 119 # Checkout your branch
 120 git checkout <branch-name>
 121
 122 # Push to your GitHub fork:
 123 git push origin <branch-name>
 124 ```
 125
 126 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.
 127
 128 #### Submit Pull Request
 129
 130 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.