1# Contributing to OpenThread
2
3We 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- [5 Contributing Documentation](#contributing-documentation)
13
14## Code of Conduct
15
16Help us keep OpenThread open and inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).
17
18## Bugs
19
20If 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.
21
22## New Features
23
24You can request a new feature by [submitting a GitHub Issue](https://github.com/openthread/openthread/issues/new).
25
26If you would like to implement a new feature, please consider the scope of the new feature:
27
28- _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.
29
30- _Small feature_: can be implemented and directly [submitted as a Pull Request](#submitting-a-pull-request).
31
32## Contributing Code
33
34The OpenThread Project follows the "Fork-and-Pull" model for accepting contributions.
35
36### Initial Setup
37
38Setup your GitHub fork and continuous-integration services:
39
401. Fork the [OpenThread repository](https://github.com/openthread/openthread) by clicking "Fork" on the web UI.
41
42Setup your local development environment:
43
44```bash
45# Clone your fork
46git clone git@github.com:<username>/openthread.git
47
48# Configure upstream alias
49git remote add upstream git@github.com:openthread/openthread.git
50```
51
52### Contributor License Agreement (CLA)
53
54Contributions 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
56You 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
62For each new feature, create a working branch:
63
64```bash
65# Create a working branch for your new feature
66git branch --track <branch-name> origin/main
67
68# Checkout the branch
69git checkout <branch-name>
70```
71
72#### Create Commits
73
74```bash
75# Add each modified file you'd like to include in the commit
76git add <file1> <file2>
77
78# Create a commit
79git commit
80```
81
82This will open up a text editor where you can craft your commit message.
83
84#### Upstream Sync and Clean Up
85
86Prior 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
88If any commits have been made to the upstream main 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 main and merge with your repo's main branch
92git checkout main
93git pull upstream main
94
95# If there were any new commits, rebase your development branch
96git checkout <branch-name>
97git rebase main
98```
99
100Now, 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
104git checkout
105git rebase -i main
106```
107
108This will open up a text editor where you can specify which commits to squash.
109
110#### Coding Conventions and Style
111
112OpenThread 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 v0.31.0](https://github.com/google/yapf) for Python.
113
114As 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
120git checkout <branch-name>
121
122# Push to your GitHub fork:
123git push origin <branch-name>
124```
125
126This will trigger continuous-integration checks using GitHub Actions. You can view the status and logs via the "Actions" tab in your fork.
127
128#### Submit Pull Request
129
130Once you've validated that all continuous-integration checks have passed, 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.
131
132#### Checks fail
133
134Once you've submitted a pull request, all continuous-integration checks are triggered again. If some of these checks fail, it could be either problems with the pull request or an intermittent failure of some test cases. For more information on the failure, check the output and download artifacts. (After all jobs in one group are completed, an `Artifacts` button appears beside the `Re-run` jobs button.) If the failure is intermittent, the check will usually pass after rerunning once or twice.
135
136We want to eliminate intermittent failures as well, so when you experience such a failure, please log an issue and attach any relevant artifacts. If the artifacts are too big, provide the link of the failed run (do not rerun checks again, or it will be overwritten). Alternatively, upload the artifacts to a file-sharing service like Google Drive and share a link to it.
137
138##### Analyze core dumps in failed checks
139
140For some checks, core dumps for crashed programs are uploaded as artifacts in a failed check. Besides core dumps, binaries and shared libraries are also uploaded so that we can analyze the dumps locally. To analyze the dumps, download the artifact `core-xxx` and unzip it. The package is in the following format:
141
142```
143|-- build
144|   `-- cmake
145|       `-- openthread-simulation-1.2
146|           `-- examples
147|               `-- apps
148|                   `-- cli
149|                       |-- ot-cli-ftd
150|                       `-- ot-cli-mtd
151|-- ot-core-dump
152|   `-- corefile-ot-cli-ftd-11323-1606274703
153`-- so-lib
154    |-- ld-linux-x86-64.so.2
155    |-- libc.so.6
156    `-- libgcc_s.so.1
157```
158
159Once unzipped:
160
1611. `cd` to the unzipped directory
1622. Run `gdb build/cmake/openthread-simulation-1.2/examples/apps/cli/ot-cli-ftd ./ot-core-dump/corefile-ot-cli-ftd-XXX`.
1633. Set the absolute path of `so-lib`. In gdb, run `set solib-absolute-prefix /ABSOLUTE/PATH/TO/so-lib/`, then run `set solib-search-path /ABSOLUTE/PATH/TO/so-lib/`.
1644. In gdb, run `backtrace` or `bt`. Then you should see the stack of the crashed program. Find and fix the problem!
165
166## Contributing Documentation
167
168Documentation undergoes the same review process as code and contributions may be mirrored on our [openthread.io](https://openthread.io) website. See the [Documentation Style Guide](https://github.com/openthread/ot-docs/blob/main/STYLE_GUIDE.md) for more information on how to author and format documentation for contribution.
169