1 # Contributing to Project Connected Home over IP
3 Want to contribute? Great! First, read this page (including the small print at
4 the end). By submitting a pull request, you represent that you have the right to
5 license your contribution to the Zigbee Alliance and the community, and agree by
6 submitting the patch that your contributions are licensed under the
7 [Apache 2.0 license](./LICENSE). Before submitting the pull request, please make
8 sure you have tested your changes and that they follow the project guidelines
11 # Contributing as an Open Source Contributor
13 As an open source contributor you can report bugs and request features in the
14 [Issue Tracker](https://github.com/project-chip/connectedhomeip/issues), as well
15 as contribute bug fixes and features that do not impact the Project CHIP
16 specification as a pull request. For example: ports of Project CHIP to add APIs
17 to alternative programming languages (e.g. Java, JS), hardware ports, or an
18 optimized implementation of existing functionality. For features that impact the
19 specification, please join Project CHIP work group within the Zigbee Alliance.
20 The requirements to become an open source contributor of the
21 [Project CHIP Repository](https://github.com/project-chip/connectedhomeip) are:
23 - Agree to the [Code of Conduct](./CODE_OF_CONDUCT.md)
24 - Agree to the [License](./LICENSE)
26 [Zigbee Project CHIP Working Group CLA](https://gist.github.com/clapre/65aa9fc63981da765039e0bb7e8701be)
28 # Contributing as a Zigbee Alliance Project CHIP Working Group Member
30 As a participant of the Zigbee Alliance Project CHIP working group, you can
31 attend working group meetings, propose changes to the Project CHIP
32 specification, and contribute code for approved updates to the specification.
33 The requirements to become a member of the
34 [Project CHIP Repository](https://github.com/project-chip/connectedhomeip) are:
36 - Must be a [Participant member](http://www.zigbeealliance.org/join) or higher
37 of the Zigbee Alliance
38 - Must be a Project CHIP Working Group member
39 - Have signed the Zigbee Project CHIP Work Group CLA
40 - Have approval from your company's official approver
44 If you find a bug in the source code, you can help us by
45 [submitting a GitHub Issue](https://github.com/project-chip/connectedhomeip/issues/new).
46 The best bug reports provide a detailed description of the issue and
47 step-by-step instructions for predictably reproducing the issue. Even better,
49 [submit a Pull Request](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md#submitting-a-pull-request)
54 You can request a new feature by
55 [submitting a GitHub Issue](https://github.com/project-chip/connectedhomeip/issues/new).
56 If you would like to implement a new feature, please consider the scope of the
59 - _Large feature_: first
60 [submit a GitHub Issue](https://github.com/project-chip/connectedhomeip/issues/new)
61 and communicate your proposal so that the community can review and provide
62 feedback. Getting early feedback will help ensure your implementation work
63 is accepted by the community. This will also allow us to better coordinate
64 our efforts and minimize duplicated effort.
65 - _Small feature_: can be implemented and directly
66 [submitted as a Pull Request](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md#submitting-a-pull-request).
70 Project CHIP follows the "Fork-and-Pull" model for accepting contributions.
74 Setup your GitHub fork and continuous-integration services:
77 [Project CHIP repository](https://github.com/project-chip/connectedhomeip) by
78 clicking "Fork" on the web UI.
80 2. All contributions must pass all checks and reviews to be accepted.
82 Setup your local development environment:
86 git clone git@github.com:<username>/connectedhomeip.git
88 # Configure upstream alias
89 git remote add upstream git@github.com:project-chip/connectedhomeip.git
92 ### Submitting a Pull Request
96 For each new feature, create a working branch:
99 # Create a working branch for your new feature
100 git branch --track <branch-name> origin/master
102 # Checkout the branch
103 git checkout <branch-name>
109 # Add each modified file you'd like to include in the commit
110 git add <file1> <file2>
116 This will open up a text editor where you can craft your commit message.
118 #### Upstream Sync and Clean Up
120 Prior to submitting your pull request, you might want to do a few things to
121 clean up your branch and make it as simple as possible for the original
122 repository's maintainer to test, accept, and merge your work.
124 If any commits have been made to the upstream master branch, you should rebase
125 your development branch so that merging it will be a simple fast-forward that
126 won't require any conflict resolution work.
129 # Fetch upstream master and merge with your repository's master branch
131 git pull upstream master
133 # If there were any new commits, rebase your development branch
134 git checkout <branch-name>
138 Now, it may be desirable to squash some of your smaller commits down into a
139 small number of larger more cohesive commits. You can do this with an
143 # Rebase all commits on your development branch
148 This will open up a text editor where you can specify which commits to squash.
153 # Checkout your branch
154 git checkout <branch-name>
156 # Push to your GitHub fork:
157 git push origin <branch-name>
160 This will trigger the continuous-integration checks. You can view the results in
161 the respective services. Note that the integration checks will report failures
164 ### Review Requirements
166 #### Documentation Best Practices
168 Project CHIP uses Doxygen to markup (or markdown) all C, C++, Objective C,
169 Objective C++, Perl, Python, and Java code. Read our
170 [Doxygen Best Practices, Conventions, and Style](https://github.com/project-chip/connectedhomeip/blob/master/docs/style/DOXYGEN.adoc)
172 #### Submit Pull Request
174 Once you've validated the CI results, go to the page for your fork on GitHub,
175 select your development branch, and click the pull request button. If you need
176 to make any adjustments to your pull request, just push the updates to GitHub.
177 Your pull request will automatically track the changes on your development
180 #### Merge Requirements
182 - Github Workflows pass
188 When can I merge? After these have been satisfied, a reviewer will merge the PR
193 Documentation undergoes the same review process as code See the
194 [Documentation Style Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/STYLE_GUIDE.md)
195 for more information on how to author and format documentation for contribution.