Want to contribute? Great! First, read this page (including the small print at the end). By submitting a pull request, you represent that you have the right to license your contribution to the Connectivity Standards Alliance and the community, and agree by submitting the patch that your contributions are licensed under the Apache 2.0 license. Before submitting the pull request, please make sure you have tested your changes and that they follow the project guidelines for contributing code.
As an open source contributor you can report bugs and request features in the Issue Tracker, as well as contribute bug fixes and features that do not impact Matter specification as a pull request. For example: ports of Matter to add APIs to alternative programming languages (e.g. Java, JS), hardware ports, or an optimized implementation of existing functionality. For features that impact the specification, please join Matter work group within the Connectivity Standards Alliance. The requirements to become an open source contributor of the Matter Repository are:
As a participant of the Connectivity Standards Alliance Matter Working Group, you can attend Working Group meetings, propose changes to the Matter specification, and contribute code for approved updates to the specification. The requirements to become a member of the Matter Repository are:
If you find a bug in the source code, you can help us by submitting a GitHub Issue. 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 with a fix.
You can request a new feature by submitting a GitHub Issue. If you would like to implement a new feature, please consider the scope of the new feature:
Matter follows the “Fork-and-Pull” model for accepting contributions.
Setup your GitHub fork and continuous-integration services:
Fork the Matter repository by clicking “Fork” on the web UI.
All contributions must pass all checks and reviews to be accepted.
Setup your local development environment:
# Clone your fork git clone git@github.com:<username>/connectedhomeip.git # Configure upstream alias git remote add upstream git@github.com:project-chip/connectedhomeip.git
For each new feature, create a working branch:
# Create a working branch for your new feature git branch --track <branch-name> origin/master # Checkout the branch git checkout <branch-name>
# 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.
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 repository'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.
# Fetch upstream master and merge with your repository'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:
# Rebase all commits on your development branch git checkout <branch-name> git rebase -i master
This will open up a text editor where you can specify which commits to squash.
# Checkout your branch git checkout <branch-name> # Push to your GitHub fork: git push origin <branch-name>
This will trigger the continuous-integration checks. You can view the results in the respective services. Note that the integration checks will report failures on occasion.
Aim to make pull requests easy to read both when viewed in a list (title only) as well as clear in content within the description.
Describe the change as a one-line in some descriptive manner. Add sufficient context for a reader to understand what is improved. If platform-specific consider adding the platform as a prefix, like [Android] or any other tags may be useful for quick filtering like [TC-ABC-1.2] to tag test changes.
Examples of descriptive titles:
[Silabs] Fix compile of SiWx917 if LED and BUTTON are disabled[Telink] Update build Dockerfile with new Zeprhy SHA: c05c4.....General Commissioning Cluster: use AttributeAccessInterface/CommandHandlerInterface for processingScenes Management/CopyScene: set access as manage instead of default to match the specFix build errors due to ChipDeviceEvent default constructor not being availableFix crash during DNSSD processing due to malformed packet[NRF] Fix crash due to stack overflow during logging for PW-RPC builds[TC-ABC-2.3] added new python test case based on test plan[TC-ABC] migrate tests from yaml to pythonExamples of titles that are vague (not clear what the change is, one would need to open the pull request for details or open additional issue in GitHub)
Work on issue 1234Fix android JniTypeWrappersFix segfault in BLEFix TC-ABC-1.2Update ReadmeEnsure that there is sufficient detail in issue summaries to make the content of the PR clear:
TLDR of the change content. This is a judgment call on details, generally you should include a what was changed and why. The change is trivial/short, this can be very short (i.e. “fixed typos” is perfectly acceptable, however if changing 100-1000s of line, the areas of changes should be explained)Fixes #.... to mark issues completed on PR merge or use #... to reference issues that are addressed.All Pull Requests MUST contain a #### Testing section that describes how the pull request was tested. Ideally every test should have automated testing, however for platform specific changes or hardware-specific issues we may not be able to have such tests (e.g. we may not BLE or NFC capability in CI). As such, manual testing is acceptable, however the description has to be detailed intentionally to avoid a bias towards marking pull requests as “manually tested” out of convenience.
Automated testing
AWESOME. You can say “unit tests added/updated” or “Integration tests updated to cover functionality” or “existing tests already cover this” (make sure they do. Integration tests often only cover happy paths).
Add any notes on not covered things. It is a judgment call on how much can be covered as 100% sounds great however not always possible.
Manual testing
Describe why automated testing is impossible in the current CI environment or difficult to add. If adding later, reference the issue to add automation and a timeline for adding such automation.
Describe in DETAIL how manual testing was done: what environment, what builds were used (build-example names are ok such as flashed qpg-qpg6105-light and used linux-x64-chip-tool-clang). Describe commands ran (often chip-tool) and physical interaction and what was observed.
Trivial/obvious change
In rare cases the change is trivial (e.g. fixing a typo in a Readme.md). Scripts still require a #### Testing section however you can be brief like N/A or checked new URL opens. Note that these cases are rare - e.g. fixing a typo in an ID still requires some description on how you checked that the new ID takes effect.
Matter uses Doxygen to markup (or markdown) all C, C++, Objective C, Objective C++, Perl, Python, and Java code. Read our Doxygen Best Practices, Conventions, and Style
Once you've validated the 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.
When can I merge? After these have been satisfied, a reviewer will merge the PR into master
Documentation undergoes the same review process as code See the Documentation Style Guide for more information on how to author and format documentation for contribution.
Merges require at least 3 approvals from unique require-reviewers lists, and all CI tests passing.
Development Lead & Vice Leads can merge a change with fewer then the required approvals have been submitted.
A separate “fast track” label will be created that will only require a single checkbox to be set, this label shall only be set by the Development Lead, and/or Vice Lead (unless they’re both unavailable, in which case a replacement can be temporarily appointed)
“Day” here means “business day” (i.e. PRs on friday do not get fast-tracked faster).
Small changes or changes that do not affect the main functionality of the code can be fast tracked immediately. Examples:
Larger functionality changes are allowed to be fast tracked with these requirements/restrictions:
Fast tracking these changes will involve resolving any obviously ‘resolved’ comments (judgment call here: were they replied to or addressed) and merging the change.
Any “request for changes” marker will always be respected unless obviously resolved (i.e. author marked “requesting changes because of X and X was done in the PR”)