From 98db6301b9582d87c777ebdbc2eaaa35db0858ae Mon Sep 17 00:00:00 2001 From: Jonathan Hui Date: Fri, 8 Dec 2023 00:21:37 -0800 Subject: [PATCH] [docs] update `CONTRIBUTING.md` (#2101) --- CONTRIBUTING.md | 38 ++++++++++++++++++++++++++++++++++---- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0421e785c8e..7724a44aafe 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ We would love for you to contribute to OpenThread and help make it even better t - [4.1 Initial Setup](#initial-setup) - [4.2 Contributor License Agreement (CLA)](#contributor-license-agreement--cla-) - [4.3 Submitting a Pull Request](#submitting-a-pull-request) +- [5 Contributing Documentation](#contributing-documentation) ## Code of Conduct @@ -37,7 +38,6 @@ The OpenThread Project follows the "Fork-and-Pull" model for accepting contribut Setup your GitHub fork and continuous-integration services: 1. Fork the [OpenThread repository](https://github.com/openthread/ot-br-posix) by clicking "Fork" on the web UI. -2. Enable [Travis CI](https://travis-ci.org/) by logging in with your GitHub account and enabling your newly created fork. We use Travis CI for Linux and macOS continuous integration checks. All contributions must pass these checks to be accepted. Setup your local development environment: @@ -109,7 +109,7 @@ This will open up a text editor where you can specify which commits to squash. #### Coding Conventions and Style -OpenThread 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 v14.0.0](https://releases.llvm.org/download.html#14.0.0) for C/C++ and [yapf](https://github.com/google/yapf) for Python. +OpenThread 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 v14.0.0](https://releases.llvm.org/download.html#14.0.0) for C/C++ and [yapf v0.31.0](https://github.com/google/yapf) for Python. As part of the cleanup process, you should also run `script/make-pretty check` to ensure that your code passes the baseline code style checks. @@ -123,8 +123,38 @@ git checkout git push origin ``` -This will trigger the Travis CI continuous-integration checks. You can view the results in the respective services. Note that the integration checks will report failures on occasion. If a failure occurs, you may try rerunning the test via the Travis web UI. +This will trigger continuous-integration checks using GitHub Actions. You can view the status and logs via the "Actions" tab in your fork. #### Submit Pull Request -Once you've validated the Travis 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. +Once 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. + +#### Checks fail + +Once 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. + +We 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. + +## Contributing Documentation + +Documentation undergoes the same review process as code and contributions may be mirrored on our [openthread.io](https://openthread.io) website. + +### Codelabs and Guides + +To review and contribute to OpenThread Codelabs and Guides, refer to the following GitHub repositories: + +- [Codelabs](https://github.com/openthread/ot-docs/tree/main/site/en/codelabs) +- [Guides](https://github.com/openthread/ot-docs/tree/main/site/en/guides) + +For information on how to author and format documentation for contribution, refer to the [Documentation Style Guide](https://github.com/openthread/ot-docs/blob/main/STYLE_GUIDE.md). + +### API Reference topics + +API Reference topics use [Doxygen comment blocks](https://www.doxygen.nl/manual/docblocks.html) to render the HTML output on [https://openthread.io/reference](https://openthread.io/reference). OpenThread scripts support the following Doxygen [special commands](https://www.doxygen.nl/manual/commands.html): + +- @file +- @brief +- @param +- @returns + +You can find most of these comments in the [OpenThread header files](https://github.com/openthread/openthread/tree/main/include/openthread). To review an example, refer to [`border_agent.h`](https://github.com/openthread/openthread/tree/main/include/openthread/border_agent.h). The Doxygen comments in `border_agent.h` output the [Border Agent](https://openthread.io/reference/group/api-border-agent) reference topic on openthread.io. For more information, refer to [Comments](https://github.com/openthread/openthread/blob/main/STYLE_GUIDE.md#comments) in the OpenThread Coding Conventions and Style guide.