From 01a47fd8afdbe14d4635e24af348a3c00d767ee3 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Thu, 5 Jan 2023 14:32:19 +0000 Subject: [PATCH 1/3] Added the example guideline and template --- docs/source/contributing.rst | 90 ++++++++++++++++++- .../ExampleTemplate/ExampleTemplate.ino | 16 ++++ .../Template/ExampleTemplate/README.md | 34 +++---- 3 files changed, 120 insertions(+), 20 deletions(-) create mode 100644 libraries/ESP32/examples/Template/ExampleTemplate/ExampleTemplate.ino rename docs/EXAMPLE_README_TEMPLATE.md => libraries/ESP32/examples/Template/ExampleTemplate/README.md (76%) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index c7d8b838f44..3d57412768c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -24,7 +24,7 @@ Before sending us a Pull Request, please consider this: * Are comments and documentation written in clear English, with no spelling or grammar errors? * Example contributions are also welcome. - * If you are contributing by adding a new example, please use the `Arduino style guide`_. + * If you are contributing by adding a new example, please use the `Arduino style guide`_ and the example guideline below. * If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits `_? @@ -39,11 +39,95 @@ Once the Pull Request is ready to merge, it will first be merged into our intern If this process passes, it will be merged onto the public github repository. +Example Contribution Guideline +------------------------------ + +Checklist +********* + +* Check if your example proposal has no similar in the project +* Use the `Arduino style guide`_ +* Add the header to all source files +* Add the `README.md` file +* Add inline comments if needed +* Test the example + +Header +****** + +All the source files must include the header with the example name and license, if applicable. You can change this header as you with, but it will be reviewed by the community and may not be accepted. + +Additionaly, you can add some description about the example, links to the documentation or authors name. Just have in mind to keep it simple and short. + +**Header Example** + +.. code-block:: arduino + + /* Wi-Fi FTM Initiator Arduino Example + + This example code is in the Public Domain (or CC0 licensed, at your option.) + + Unless required by applicable law or agreed to in writing, this + software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + CONDITIONS OF ANY KIND, either express or implied. + */ + + +README file +*********** + +The **README.md** file should contain the example details. + +Please see the recommended **README.md** file in the `example template folder `_. + +Inline Comments +*************** + +Inline comments are important if the example contains complex algorithms os specific configuration that the user needs to change. + +**Example** + +.. code-block:: arduino + + // Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64) + +and + +.. code-block:: arduino + + const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled + const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password + +Testing +******* + +Be sure you have tested the example in all the supported targets. If the example works only with specific targets, add this information in the **README.md** file on the **Supported Targets** and in the example code as inline comment. + +**Example** + +.. code-block:: arduino + + /* + THIS FEATURE IS SUPPORTED ONLY BY ESP32-S2 AND ESP32-C3 + */ + +and + +.. code-block:: markdown + + Currently, this example supports the following targets. + + | Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | + | ----------------- | ----- | -------- | -------- | -------- | + +Example Template +**************** + +The example template can be found `here `_ and can be used as a reference. + Legal Part ---------- Before a contribution can be accepted, you will need to sign our contributor-agreement. You will be prompted for this automatically as part of the Pull Request process. - - .. _Arduino style guide: https://www.arduino.cc/en/Reference/StyleGuide diff --git a/libraries/ESP32/examples/Template/ExampleTemplate/ExampleTemplate.ino b/libraries/ESP32/examples/Template/ExampleTemplate/ExampleTemplate.ino new file mode 100644 index 00000000000..ff9733d1cd4 --- /dev/null +++ b/libraries/ESP32/examples/Template/ExampleTemplate/ExampleTemplate.ino @@ -0,0 +1,16 @@ +/* Arduino Example Template + + This example code is in the Public Domain (or CC0 licensed, at your option.) + + Unless required by applicable law or agreed to in writing, this + software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR + CONDITIONS OF ANY KIND, either express or implied. +*/ + +void setup() { + +} + +void loop() { + +} diff --git a/docs/EXAMPLE_README_TEMPLATE.md b/libraries/ESP32/examples/Template/ExampleTemplate/README.md similarity index 76% rename from docs/EXAMPLE_README_TEMPLATE.md rename to libraries/ESP32/examples/Template/ExampleTemplate/README.md index 094b78c80fe..9819880d4f4 100644 --- a/docs/EXAMPLE_README_TEMPLATE.md +++ b/libraries/ESP32/examples/Template/ExampleTemplate/README.md @@ -1,6 +1,6 @@ # Arduino-ESP32 Example/Library Name ==(REQUIRED)== -==*Add a brief description about this example/library here!*== +==*Add a brief description of this example/library here!*== This example/library demonstrates how to create a new example README file. @@ -15,33 +15,33 @@ Currently, this example supports the following targets. ## How to Use Example/Library ==(OPTIONAL)== -==*Add a brief description on how to use this example.*== +==*Add a brief description of how to use this example.*== * How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). ### Hardware Connection ==(OPTIONAL)== -==*Add a brief description about wiring or any other hardware specific connection.*== +==*Add a brief description of wiring or any other hardware-specific connection.*== To use this example, you need to connect the LED to the `GPIOx`. SDCard GPIO connection scheme: -| SDCard Pin | Function | GPIO | +| SDCard Pin | Function | GPIO | | ----------- | -------- | ------ | -| 1 | CS | GPIO5 | -| 2 | DI/MOSI | GPIO23 | -| 3 | VSS/GND | GND | -| 4 | VDD/3V3 | 3V3 | -| 5 | SCLK | GPIO18 | -| 6 | VSS/GND | GND | -| 7 | DO/MISO | GPIO19 | +| 1 | CS | GPIO5 | +| 2 | DI/MOSI | GPIO23 | +| 3 | VSS/GND | GND | +| 4 | VDD/3V3 | 3V3 | +| 5 | SCLK | GPIO18 | +| 6 | VSS/GND | GND | +| 7 | DO/MISO | GPIO19 | To add images, please create a folder `_asset` inside the example folder to add the relevant images. ### Configure the Project ==(OPTIONAL)== -==*Add a brief description about this example here!*== +==*Add a brief description of this example here!*== Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`. @@ -66,7 +66,7 @@ To get more information about the Espressif boards see [Espressif Development Ki #### Using Platform IO -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. +* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. ## Example/Log Output ==(OPTIONAL)== @@ -98,21 +98,21 @@ Chip ID: 3957392 * **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. * **COM port not detected:** Check the USB cable and the USB to Serial driver installation. -If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). +If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). ## Contribute ==(REQUIRED)== -==*Do not change! Keep as is.*== +==*Do not change! Keep it as is.*== To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! -Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else. +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. ## Resources ==(REQUIRED)== -==*Do not change here! Keep as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== +==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== * Official ESP32 Forum: [Link](https://esp32.com) * Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) From 0514414e005ac814c33d6fdff57ebcff612a3da4 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 9 Jan 2023 15:09:02 +0000 Subject: [PATCH 2/3] PR review changes with some typos and grammar fixes --- docs/source/contributing.rst | 41 ++++++++++++++++++------------------ 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 3d57412768c..365eb64b61c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -15,16 +15,17 @@ Before Contributing Before sending us a Pull Request, please consider this: -* Is the contribution entirely your own work, or is it already licensed under an LGPL 2.1 compatible Open Source License? If not, we unfortunately cannot accept it. +* Is the contribution entirely your own work, or is it already licensed under an LGPL 2.1 compatible Open Source License? If not, we, unfortunately, cannot accept it. -* Is the code adequately commented for people to understand how it is structured? +* Is the code adequately commented on to people understand how it is structured? * Is there documentation or examples that go with code contributions? * Are comments and documentation written in clear English, with no spelling or grammar errors? * Example contributions are also welcome. - * If you are contributing by adding a new example, please use the `Arduino style guide`_ and the example guideline below. + + * If you are contributing by adding a new example, please use the `Arduino style guide`_ and the example guideline below. * If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits `_? @@ -33,11 +34,11 @@ If you're unsure about any of these points, please open the Pull Request anyhow Pull Request Process -------------------- -After you open the Pull Request, there will probably be some discussion in the comments' field of the request itself. +After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing. -If this process passes, it will be merged onto the public github repository. +If this process passes, it will be merged into the public GitHub repository. Example Contribution Guideline ------------------------------ @@ -45,23 +46,23 @@ Example Contribution Guideline Checklist ********* -* Check if your example proposal has no similar in the project +* Check if your example proposal has no similarities to the project * Use the `Arduino style guide`_ * Add the header to all source files -* Add the `README.md` file +* Add the `README.md` file * Add inline comments if needed * Test the example Header ****** -All the source files must include the header with the example name and license, if applicable. You can change this header as you with, but it will be reviewed by the community and may not be accepted. +All the source files must include the header with the example name and license, if applicable. You can change this header as you wish, but it will be reviewed by the community and may not be accepted. -Additionaly, you can add some description about the example, links to the documentation or authors name. Just have in mind to keep it simple and short. +Additionally, you can add some description about the example, links to the documentation, or the author's name. Just have in mind to keep it simple and short. **Header Example** -.. code-block:: arduino +.. code-block:: arduino /* Wi-Fi FTM Initiator Arduino Example @@ -76,24 +77,24 @@ Additionaly, you can add some description about the example, links to the docume README file *********** -The **README.md** file should contain the example details. +The **README.md** file should contain the example details. -Please see the recommended **README.md** file in the `example template folder `_. +Please see the recommended **README.md** file in the `example template folder `_. Inline Comments *************** -Inline comments are important if the example contains complex algorithms os specific configuration that the user needs to change. +Inline comments are important if the example contains complex algorithms or specific configurations that the user needs to change. **Example** -.. code-block:: arduino +.. code-block:: arduino // Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64) and -.. code-block:: arduino +.. code-block:: arduino const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password @@ -101,11 +102,11 @@ and Testing ******* -Be sure you have tested the example in all the supported targets. If the example works only with specific targets, add this information in the **README.md** file on the **Supported Targets** and in the example code as inline comment. +Be sure you have tested the example in all the supported targets. If the example works only with specific targets, add this information in the **README.md** file on the **Supported Targets** and in the example code as an inline comment. **Example** -.. code-block:: arduino +.. code-block:: arduino /* THIS FEATURE IS SUPPORTED ONLY BY ESP32-S2 AND ESP32-C3 @@ -113,7 +114,7 @@ Be sure you have tested the example in all the supported targets. If the example and -.. code-block:: markdown +.. code-block:: markdown Currently, this example supports the following targets. @@ -123,11 +124,11 @@ and Example Template **************** -The example template can be found `here `_ and can be used as a reference. +The example template can be found `here `_ and can be used as a reference. Legal Part ---------- -Before a contribution can be accepted, you will need to sign our contributor-agreement. You will be prompted for this automatically as part of the Pull Request process. +Before a contribution can be accepted, you will need to sign our contributor agreement. You will be prompted for this automatically as part of the Pull Request process. .. _Arduino style guide: https://www.arduino.cc/en/Reference/StyleGuide From e88f547f77e7ab6352b52dc2185aaa2e821e224f Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Mon, 16 Jan 2023 14:28:07 +0000 Subject: [PATCH 3/3] Changes according to the PR review --- CONTRIBUTING.rst | 50 ------------------------------------ docs/source/contributing.rst | 14 ++++++---- 2 files changed, 9 insertions(+), 55 deletions(-) delete mode 100644 CONTRIBUTING.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 0c0d6936474..00000000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,50 +0,0 @@ -Contributions Guide -=================== - -We welcome contributions to the Arduino ESP32 project! - -How to Contribute ------------------ - -Contributions to Arduino ESP32 - fixing bugs, adding features, adding documentation - are welcome. We accept contributions via `Github Pull Requests `_. - -Before Contributing -------------------- - -Before sending us a Pull Request, please consider this list of points: - -* Is the contribution entirely your own work, or already licensed under an LGPL 2.1 compatible Open Source License? If not then we unfortunately cannot accept it. - -* Is the code adequately commented for people to understand how it is structured? - -* Is there documentation or examples that go with code contributions? - -* Are comments and documentation written in clear English, with no spelling or grammar errors? - -* Example contributions are also welcome. - -* If the contribution contains multiple commits, are they grouped together into logical changes (one major change per pull request)? Are any commits with names like "fixed typo" `squashed into previous commits `_? - -* If you're unsure about any of these points, please open the Pull Request anyhow and then ask us for feedback. - -Pull Request Process --------------------- - -After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. - -Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing. - -If this process passes, it will be merged onto the public github repository. - -Legal Part ----------- - -Before a contribution can be accepted, you will need to sign our :doc:`contributor-agreement`. You will be prompted for this automatically as part of the Pull Request process. - -Related Documents ------------------ - -.. toctree:: - :maxdepth: 1 - - contributor-agreement diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 365eb64b61c..9ebc77b3780 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -15,9 +15,9 @@ Before Contributing Before sending us a Pull Request, please consider this: -* Is the contribution entirely your own work, or is it already licensed under an LGPL 2.1 compatible Open Source License? If not, we, unfortunately, cannot accept it. +* Is the contribution entirely your own work, or is it already licensed under an LGPL 2.1 compatible Open Source License? If not, cannot accept it. -* Is the code adequately commented on to people understand how it is structured? +* Is the code adequately commented and can people understand how it is structured? * Is there documentation or examples that go with code contributions? @@ -36,7 +36,7 @@ Pull Request Process After you open the Pull Request, there will probably be some discussion in the comments field of the request itself. -Once the Pull Request is ready to merge, it will first be merged into our internal git system for in-house automated testing. +Once the Pull Request is ready to merge, it will first be merged into our internal git system for "in-house" automated testing. If this process passes, it will be merged into the public GitHub repository. @@ -46,7 +46,7 @@ Example Contribution Guideline Checklist ********* -* Check if your example proposal has no similarities to the project +* Check if your example proposal has no similarities to the project (**already existing examples**) * Use the `Arduino style guide`_ * Add the header to all source files * Add the `README.md` file @@ -58,7 +58,7 @@ Header All the source files must include the header with the example name and license, if applicable. You can change this header as you wish, but it will be reviewed by the community and may not be accepted. -Additionally, you can add some description about the example, links to the documentation, or the author's name. Just have in mind to keep it simple and short. +Ideally, you can add some description about the example, links to the documentation, or the author's name. Just have in mind to keep it simple and short. **Header Example** @@ -86,8 +86,12 @@ Inline Comments Inline comments are important if the example contains complex algorithms or specific configurations that the user needs to change. +Brief and clear inline comments are really helpful for the example understanding and it's fast usage. + **Example** +See the `FTM example `_ as a reference. + .. code-block:: arduino // Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64)