From d4a0615124de5665cd2f2f5da39467213e2605a2 Mon Sep 17 00:00:00 2001 From: Justin Wood Date: Wed, 1 Jul 2020 08:58:02 -0700 Subject: [PATCH] Ready README.md for open source (#1000) * Cleanup * Updating text * Updating files * Removing this for now * Removing these placeholders * Updating based on feedback * Updating license text * Removing this config * Updating CLA * Removing tests * Adding CircleCI badge * Shield style --- CONTRIBUTING.md | 203 ++++++++++------------------------ CONTRIBUTORS.md | 4 - Makefile.am | 1 - README.md | 100 +++++++++-------- configure.ac | 1 - tests/Makefile.am | 42 ------- tests/certification/README.md | 1 - tests/docs/README.md | 1 - tests/fuzz/README.md | 1 - tests/integration/README.md | 1 - 10 files changed, 109 insertions(+), 246 deletions(-) delete mode 100644 CONTRIBUTORS.md delete mode 100644 tests/Makefile.am delete mode 100644 tests/certification/README.md delete mode 100644 tests/docs/README.md delete mode 100644 tests/fuzz/README.md delete mode 100644 tests/integration/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index afe9bb64de79ce..ce5743b2b16186 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,106 +1,58 @@ -# Contributing to CHIP +# Contributing to Project Connected Home over IP 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 Zigbee and the community, and agree by submitting -the patch that your contributions are licensed under the -[Apache 2.0 license](./LICENSE). +license your contribution to the Zigbee Alliance and the community, and agree by +submitting the patch that your contributions are licensed under the +[Apache 2.0 license](./LICENSE). Before submitting the pull request, please make +sure you have tested your changes and that they follow the project guidelines +for contributing code. + +# Contributing as an Open Source Contributor + +As an open source contributor you can report bugs and request features in the +[Issue Tracker](https://github.com/project-chip/connectedhomeip/issues), as well +as contribute bug fixes and features that do not impact the Project CHIP +specification as a pull request. For example: ports of Project CHIP 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 Project CHIP work group within the Zigbee Alliance. +The requirements to become an open source contributor of the +[Project CHIP Repository](https://github.com/project-chip/connectedhomeip) are: -Before submitting the pull request, please make sure you have tested your -changes and that they follow the project -[guidelines for contributing code](#pull-request-requirements). - -## Becoming a Member - -Currently these are the requirements to becoming a member of the -[Project-CHIP Repository](https://github.com/project-chip/connectedhomeip) - -- Must be a member of the Zigbee Alliance CHIP TSG Working Group -- Have signed the Zigbee CHIP WG CLA -- Have signed up as a Tiger team member in one of the follow roles: Lead, Spec - Writer, Developer (or exception granted), Code Approvers, or Support Staff -- Have approval from your company's official approver +- Agree to the [Code of Conduct](./CODE_OF_CONDUCT.md) +- Agree to the [License](./LICENSE) +- Have signed the + [Zigbee Project CHIP Working Group CLA](https://gist.github.com/clapre/65aa9fc63981da765039e0bb7e8701be) -## Becoming a Contributor +# Contributing as a Zigbee Alliance Project CHIP Working Group Member -Currently these are the requirements to becoming a member of the -[Project-CHIP Repository](https://github.com/project-chip/connectedhomeip) +As a participant of the Zigbee Alliance Project CHIP working group, you can +attend working group meetings, propose changes to the Project CHIP +specification, and contribute code for approved updates to the specification. +The requirements to become a member of the +[Project CHIP Repository](https://github.com/project-chip/connectedhomeip) are: -- Must be a member of the Zigbee Alliance CHIP TSG Working Group -- Have signed the Zigbee CHIP WG CLA -- Agree to the [Code of Conduct](./CODE_OF_CONDUCT.md) -- Agree to the [License](./LICENSE) -- Have signed up as a Tiger team member in one of the follow roles: Lead, Spec - Writer, Developer (or exception granted), Code Approvers, or Support Staff +- Must be a [Participant member](http://www.zigbeealliance.org/join) or higher + of the Zigbee Alliance +- Must be a Project CHIP Working Group member +- Have signed the Zigbee Project CHIP Work Group CLA - Have approval from your company's official approver -## Getting Started - -This repository contains the source code that implements the CHIP specification. -It scalably implements the specification that may be used on a wide range of -platforms including Android/iOS and Darwin/Linux down to embedded MCU-based -platforms running FreeRTOS and LwIP. - -The source code can be built to generate: - -- **Libraries** that can be built for iOS, Android or desktop (Linux/Mac) - targets. These libraries could further be integrated into applications that - talk _CHIP_. -- **Firmwares/Embedded Applications** that can be built for the supported - embedded platforms. -- **Desktop Application** that can be used in conjunction with the embedded - applications above to validate the end-to-end CHIP workflow. - -### Building your first application - -- Building the firmware: This repository implements the CHIP specification on - 3 transports: 802.15.4 Thread, BLE and Wi-Fi. The examples/ directory - contains example applications for all these 3 transports using 3 embedded - platforms. Please visit their respective directories for instructions on how - to build and deploy on these platforms. - - NRF5 (for 802.15.4 Thread): in - [examples/lock-app/nrf5](examples/lock-app/nrf5) - - EFR32 (for BLE): in [examples/lock-app/efr32](examples/lock-app/efr32) - - ESP32 (for Wi-Fi or BLE): in - [examples/wifi-echo/server/esp32](examples/wifi-echo/server/esp32) -- Building the host utility: The host utility can be used in conjunction with - the embedded platform for end-to-end validation. Please visit the - [examples/chip-tool](examples/chip-tool) directory for further instructions. - -### Where should I begin? - -- Good First Issue: Certain issues are marked with a label - [Good First Issue](https://github.com/project-chip/connectedhomeip/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). - These issues are what we believe may be good starting points for getting - your hands dirty. -- TODOs: Most items that will require work are captured in the GitHub issues - of this project. This serves as a good TODO list for the next steps. -- Milestones: A list of - [milestones](https://github.com/project-chip/connectedhomeip/milestones) are - maintained in this project. This should provide some idea of where things - are headed. Note that given the early days of this project, most of these - are not hard deadlines. - -### Where is the spec? - -- The specification is evolving in various tiger teams. Members belonging to - various tiger teams may contribute experimental code for the general - direction where the spec is headed. Once a specification is fairly - finalised, it will be available/committed in the [docs/specs](docs/specs). - -## Bugs +# Bugs If you find a bug in the source code, you can help us by [submitting a GitHub Issue](https://github.com/project-chip/connectedhomeip/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. +you can +[submit a Pull Request](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md#submitting-a-pull-request) +with a fix. -## New Features +# New Features You can request a new feature by [submitting a GitHub Issue](https://github.com/project-chip/connectedhomeip/issues/new). - If you would like to implement a new feature, please consider the scope of the new feature: @@ -110,20 +62,20 @@ new feature: 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. - - _Small feature_: can be implemented and directly - [submitted as a Pull Request](#submitting-a-pull-request). + [submitted as a Pull Request](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md#submitting-a-pull-request). -## Contributing Code +# Contributing Code -CHIP follows the "Fork-and-Pull" model for accepting contributions. +Project CHIP follows the "Fork-and-Pull" model for accepting contributions. ### Initial Setup Setup your GitHub fork and continuous-integration services: -1. Fork the [CHIP repository](https://github.com/project-chip/connectedhomeip) - by clicking "Fork" on the web UI. +1. Fork the + [Project CHIP repository](https://github.com/project-chip/connectedhomeip) by + clicking "Fork" on the web UI. 2. All contributions must pass all checks and reviews to be accepted. @@ -209,53 +161,13 @@ 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. -#### Pull Request Requirements - -CHIP considers there to be a few different types of pull requests: - -- Trivial bug fix -- - Description 1 -- - Description 2 -- Small Bug fix -- - Description 1 -- - Description 2 -- Bug Fix -- - Description 1 -- - Description 2 -- Significant Change -- - Description 1 -- - Description 2 -- Feature -- - Description 1 -- - Description 2 -- Architecture Change -- - Description 1 -- - Description 2 - -### Prior to review, all changes require: - -- [GitHub Workflows](.github/workflows) pass -- [Certification Tests](tests/certification/README.md) pass -- [Fuzz Tests](tests/fuzz/README.md) pass -- [Integration Tests](tests/integration/README.md) pass -- Linting passes -- Code style passes - ### Review Requirements -Each type of change has unique additional requirements, here's a table of those: - -| Type | Reviewer Requirements | New Unit Tests | New Certification Tests | New Fuzz Tests | New Integration Tests | -| ------------------- | -------------------------------------- | -------------- | ----------------------- | -------------- | --------------------- | -| Trivial bug fix | 3 [approved reviewers](./REVIEWERS.md) | | | | | -| Small Bug fix | 3 [approved reviewers](./REVIEWERS.md) | | | | | -| Bug Fix | 3 [approved reviewers](./REVIEWERS.md) | | | | | -| Significant Change | 3 [approved reviewers](./REVIEWERS.md) | | | | | -| Feature | 3 [approved reviewers](./REVIEWERS.md) | | | | | -| Architecture Change | 3 [approved reviewers](./REVIEWERS.md) | | | | | +#### Documentation Best Practices -Note: Where multiple reviewers are required, each reviewer must be from a -different member company. +Project CHIP 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](https://github.com/project-chip/connectedhomeip/blob/master/docs/style/DOXYGEN.adoc) #### Submit Pull Request @@ -267,20 +179,17 @@ branch and update. #### Merge Requirements -- Passes [Review Requirements](#review-requirements) -- [GitHub Workflows](.github/workflows) pass -- [Certification Tests](tests/certification/README.md) pass -- [Fuzz Tests](tests/fuzz/README.md) pass -- [Integration Tests](tests/integration/README.md) pass +- Github Workflows pass +- Builds pass +- Tests pass - Linting passes - Code style passes -**When can I merge?** After these have been satisfied, any reviewer, or the -originator can merge the PR into master. - -### Documentation +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 +#### Documentation -See the [Documentation Style Guide](docs/STYLE_GUIDE.md) for more information on -how to author and format documentation for contribution. +Documentation undergoes the same review process as code See the +[Documentation Style Guide](https://github.com/project-chip/connectedhomeip/blob/master/docs/STYLE_GUIDE.md) +for more information on how to author and format documentation for contribution. diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md deleted file mode 100644 index a6c30831c9ed11..00000000000000 --- a/CONTRIBUTORS.md +++ /dev/null @@ -1,4 +0,0 @@ -The following organizations and individuals have contributed to the CHIP SDK: - -- Apple Inc -- Google Inc diff --git a/Makefile.am b/Makefile.am index fcce0293287cdd..23b5e0f6d36891 100644 --- a/Makefile.am +++ b/Makefile.am @@ -34,7 +34,6 @@ SUBDIRS = \ examples \ third_party \ src \ - tests \ docs \ $(NULL) diff --git a/README.md b/README.md index 4b7e7abf5474cc..4a9bd43b03096f 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,67 @@ # Connected Home over IP -[![Build Status](https://travis-ci.com/project-chip/connectedhomeip.svg?token=hBypqqXx6Ha9n3zZgyp7&branch=master)](https://travis-ci.com/project-chip/connectedhomeip) -[![codecov](https://codecov.io/gh/project-chip/connectedhomeip/branch/master/graph/badge.svg?token=KP9791CN9W)](https://codecov.io/gh/project-chip/connectedhomeip) +[![project-chip](https://circleci.com/gh/project-chip/connectedhomeip.svg?style=shield&circle-token=7318eddc58468689cd2ae9c5c82fe8dcf24902f6)](https://app.circleci.com/pipelines/github/project-chip/connectedhomeip?branch=master) -# Getting started with CHIP +# What is Project Connected Home over IP? -All documentation is inside of the [docs section](./docs/README.md) +Visit connectedhomeip.com to learn more. -Instructions about how to build and develop CHIP can be found -[here](./docs/README.md#building-and-developing). +# Current Status of Project Connected Home over IP + +The Zigbee Alliance officially opened the Project Connected Home over IP +(Project CHIP) Working Group on January 17 and is in the process of drafting the +specification. + +The Project’s design and technical processes are intended to be open and +transparent to the general public, including to Work Group non-members wherever +possible. The availability of this GitHub repository and its source code under +an Apache v2 license is an important and demonstrable step to achieving this +commitment. + +The Project endeavors to bring together the best aspects of market-tested +technologies and to redeploy them as a unified and cohesive whole-system +solution. The overall goal of this approach is to bring the benefits of the +Project to consumers and manufacturers as quickly as possible. As a result, what +you observe in this repository is an implementation-first approach to the +technical specification, vetting integrations in practice. -# Need help? +# How to Contribute -There are numerous avenues for CHIP support: +We would love for you to contribute to Project Connected Home over IP. Read our +contribution guidelines +[here](https://github.com/project-chip/connectedhomeip/blob/master/CONTRIBUTING.md). -- Bugs and feature requests - [submit to the Issue Tracker](https://github.com/project-chip/connectedhomeip/issues) -- Stack Overflow - [post questions using the chip tag](http://stackoverflow.com/questions/tagged/chip) +# Building and Developing in Project + +Instructions about how to build Project Connected Home over IP can be found +[here](./docs/README.md#building-and-developing). # Directory Structure -The CHIP repository is structured as follows: - -| File / Folder | Contents | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------- | -| `.default-version` | Default CHIP version if none is available via source code control tags, `.dist-version`, or `.local-version`. | -| `bootstrap` | GNU autotools bootstrap script for the CHIP build system. | -| `bootstrap-configure` | Convenience script that will bootstrap the CHIP build system, via `bootstrap`, and invoke `configure`. | -| `build/` | Build system support content and build output directories | -| `BUILDING.md` | More detailed information on configuring and building CHIP for different targets | -| `CODE_OF_CONDUCT.md` | Code of Conduct for CHIP, and contributions to it | -| `CONTRIBUTING.md` | Guidelines for contributing to CHIP | -| `CONTRIBUTORS.md` | Contributors to CHIP | -| `docs/` | Documentation | -| `examples/` | Example firmware applications that demonstrate use of CHIP technology | -| `integrations/` | Third party integrations related to this project | -| `integrations/github/` | GitHub integrations related to this project | -| `integrations/github/actions` | GitHub actions related to this project | -| `integrations/docker/` | Docker scripts and Dockerfiles | -| `LICENSE` | CHIP License file (Apache 2.0) | -| `Makefile-Android` | Convenience makefile for building CHIP against Android. | -| `Makefile-iOS` | Convenience makefile for building CHIP against iOS. | -| `Makefile-Standalone` | Convenience makefile for building CHIP as a standalone package on desktop and server systems. | -| `README.md` | This file | -| `src/` | Implementation of CHIP | -| `tests/` | Tests for CHIP | -| `third_party/` | Third-party code used by CHIP. | -| `tools/` | Tools needed to work with the CHIP repo, as well as develop in the repository | - -# Contributing - -We would love for you to contribute to CHIP and help make it even better than it -is today! See the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more -information. +The Connected Home over IP repository is structured as follows: + +| File / Folder | Contents | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | +| `.default-version` | Default Project CHIP version if none is available via source code control tags, `.dist-version`, or `.local-version` | +| `bootstrap` | GNU autotools bootstrap script for the Project CHIP build system | +| `bootstrap-configure` | Convenience script that will bootstrap the Project CHIP build system, via `bootstrap`, and invoke `configure` | +| `build/` | Build system support content and build output directories | +| `BUILDING.md` | More detailed information on configuring and building Project CHIP for different targets | +| `CODE_OF_CONDUCT.md` | Code of Conduct for Project CHIP, and contributions to it | +| `CONTRIBUTING.md` | Guidelines for contributing to Project CHIP | +| `CONTRIBUTORS.md` | Contributors to Project CHIP | +| `docs/` | Documentation | +| `examples/` | Example firmware applications that demonstrate use of Project CHIP technology | +| `integrations/` | Third party integrations related to this project | +| `integrations/docker/` | Docker scripts and Dockerfiles | +| `LICENSE` | Project CHIP [License file](./LICENSE) (Apache 2.0) | +| `Makefile-Android` | Convenience makefile for building Project CHIP against Android | +| `Makefile-Standalone` | Convenience makefile for building Project CHIP as a standalone package on desktop and server systems | +| `README.md` | This file | +| `src/` | Implementation of Project CHIP | +| `third_party/` | Third-party code used by Project CHIP | +| `tools/` | Tools needed to work with the Project CHIP repo | # License -CHIP is released under the [Apache 2.0 license](./LICENSE) Please read more -details therein +Project CHIP is released under the [Apache 2.0 license](./LICENSE). diff --git a/configure.ac b/configure.ac index d7040adcb5b920..ea193f50e50b3b 100644 --- a/configure.ac +++ b/configure.ac @@ -2177,7 +2177,6 @@ src/platform/tests/Makefile src/qrcodetool/Makefile src/transport/Makefile src/transport/tests/Makefile -tests/Makefile ]) # diff --git a/tests/Makefile.am b/tests/Makefile.am deleted file mode 100644 index 5f7bff3b4a8c97..00000000000000 --- a/tests/Makefile.am +++ /dev/null @@ -1,42 +0,0 @@ -# -# Copyright (c) 2020 Project CHIP Authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -# -# Description: -# This file is the GNU automake template for the Project CHIP -# tests directory. -# - -include $(abs_top_nlbuild_autotools_dir)/automake/pre.am - -EXTRA_DIST = \ - integration/README.md \ - docs/README.md \ - fuzz/README.md \ - certification/README.md \ - $(NULL) - -# Always package (e.g. for 'make dist') these subdirectories. - -DIST_SUBDIRS = \ - $(NULL) - -# Always build (e.g. for 'make all') these subdirectories. - -SUBDIRS = \ - $(NULL) - -include $(abs_top_nlbuild_autotools_dir)/automake/post.am diff --git a/tests/certification/README.md b/tests/certification/README.md deleted file mode 100644 index d587360fa6c165..00000000000000 --- a/tests/certification/README.md +++ /dev/null @@ -1 +0,0 @@ -## Certification Test Suites diff --git a/tests/docs/README.md b/tests/docs/README.md deleted file mode 100644 index 2212576b76ee3f..00000000000000 --- a/tests/docs/README.md +++ /dev/null @@ -1 +0,0 @@ -# Test Documentation diff --git a/tests/fuzz/README.md b/tests/fuzz/README.md deleted file mode 100644 index f7799ef976df08..00000000000000 --- a/tests/fuzz/README.md +++ /dev/null @@ -1 +0,0 @@ -## Fuzz Test Suites diff --git a/tests/integration/README.md b/tests/integration/README.md deleted file mode 100644 index c7476fac126abd..00000000000000 --- a/tests/integration/README.md +++ /dev/null @@ -1 +0,0 @@ -## Integration Test Suites