CONTRIBUTING.md

   1 # Contributing to Project Connected Home over IP
   2
   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
   9 for contributing code.
  10
  11 # Contributing as an Open Source Contributor
  12
  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:
  22
  23 -   Agree to the [Code of Conduct](./CODE_OF_CONDUCT.md)
  24 -   Agree to the [License](./LICENSE)
  25 -   Have signed the
  26     [Zigbee Project CHIP Working Group CLA](https://gist.github.com/clapre/65aa9fc63981da765039e0bb7e8701be)
  27
  28 # Contributing as a Zigbee Alliance Project CHIP Working Group Member
  29
  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:
  35
  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
  41
  42 # Bugs
  43
  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,
  48 you can
  49 [submit a Pull Request](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md#submitting-a-pull-request)
  50 with a fix.
  51
  52 # New Features
  53
  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
  57 new feature:
  58
  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).
  67
  68 # Contributing Code
  69
  70 Project CHIP follows the "Fork-and-Pull" model for accepting contributions.
  71
  72 ### Initial Setup
  73
  74 Setup your GitHub fork and continuous-integration services:
  75
  76 1. Fork the
  77    [Project CHIP repository](https://github.com/project-chip/connectedhomeip) by
  78    clicking "Fork" on the web UI.
  79
  80 2. All contributions must pass all checks and reviews to be accepted.
  81
  82 Setup your local development environment:
  83
  84 ```bash
  85 # Clone your fork
  86 git clone git@github.com:<username>/connectedhomeip.git
  87
  88 # Configure upstream alias
  89 git remote add upstream git@github.com:project-chip/connectedhomeip.git
  90 ```
  91
  92 ### Submitting a Pull Request
  93
  94 #### Branch
  95
  96 For each new feature, create a working branch:
  97
  98 ```bash
  99 # Create a working branch for your new feature
 100 git branch --track <branch-name> origin/master
 101
 102 # Checkout the branch
 103 git checkout <branch-name>
 104 ```
 105
 106 #### Create Commits
 107
 108 ```bash
 109 # Add each modified file you'd like to include in the commit
 110 git add <file1> <file2>
 111
 112 # Create a commit
 113 git commit
 114 ```
 115
 116 This will open up a text editor where you can craft your commit message.
 117
 118 #### Upstream Sync and Clean Up
 119
 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.
 123
 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.
 127
 128 ```bash
 129 # Fetch upstream master and merge with your repository's master branch
 130 git checkout master
 131 git pull upstream master
 132
 133 # If there were any new commits, rebase your development branch
 134 git checkout <branch-name>
 135 git rebase master
 136 ```
 137
 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
 140 interactive rebase:
 141
 142 ```bash
 143 # Rebase all commits on your development branch
 144 git checkout
 145 git rebase -i master
 146 ```
 147
 148 This will open up a text editor where you can specify which commits to squash.
 149
 150 #### Push and Test
 151
 152 ```bash
 153 # Checkout your branch
 154 git checkout <branch-name>
 155
 156 # Push to your GitHub fork:
 157 git push origin <branch-name>
 158 ```
 159
 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
 162 on occasion.
 163
 164 ### Review Requirements
 165
 166 #### Documentation Best Practices
 167
 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)
 171
 172 #### Submit Pull Request
 173
 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
 178 branch and update.
 179
 180 #### Merge Requirements
 181
 182 -   Github Workflows pass
 183 -   Builds pass
 184 -   Tests pass
 185 -   Linting passes
 186 -   Code style passes
 187
 188 When can I merge? After these have been satisfied, a reviewer will merge the PR
 189 into master
 190
 191 #### Documentation
 192
 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.