Skip to content

Commit 01a47fd

Browse files
pedrominatelpedrominatel
committed
Added the example guideline and template
1 parent 0ad5eef commit 01a47fd

File tree

3 files changed

+120
-20
lines changed

3 files changed

+120
-20
lines changed

‎docs/source/contributing.rst

Lines changed: 87 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ Before sending us a Pull Request, please consider this:
2424
* Are comments and documentation written in clear English, with no spelling or grammar errors?
2525

2626
* Example contributions are also welcome.
27-
* If you are contributing by adding a new example, please use the `Arduino style guide`_.
27+
* If you are contributing by adding a new example, please use the `Arduino style guide`_ and the example guideline below.
2828

2929
* 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 <https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit/>`_?
3030

@@ -39,11 +39,95 @@ Once the Pull Request is ready to merge, it will first be merged into our intern
3939

4040
If this process passes, it will be merged onto the public github repository.
4141

42+
Example Contribution Guideline
43+
------------------------------
44+
45+
Checklist
46+
*********
47+
48+
* Check if your example proposal has no similar in the project
49+
* Use the `Arduino style guide`_
50+
* Add the header to all source files
51+
* Add the `README.md` file
52+
* Add inline comments if needed
53+
* Test the example
54+
55+
Header
56+
******
57+
58+
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.
59+
60+
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.
61+
62+
**Header Example**
63+
64+
.. code-block:: arduino
65+
66+
/* Wi-Fi FTM Initiator Arduino Example
67+
68+
This example code is in the Public Domain (or CC0 licensed, at your option.)
69+
70+
Unless required by applicable law or agreed to in writing, this
71+
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
72+
CONDITIONS OF ANY KIND, either express or implied.
73+
*/
74+
75+
76+
README file
77+
***********
78+
79+
The **README.md** file should contain the example details.
80+
81+
Please see the recommended **README.md** file in the `example template folder <https://github.com/espressif/arduino-esp32/tree/master/libraries/ESP32/examples/Template/ExampleTemplate>`_.
82+
83+
Inline Comments
84+
***************
85+
86+
Inline comments are important if the example contains complex algorithms os specific configuration that the user needs to change.
87+
88+
**Example**
89+
90+
.. code-block:: arduino
91+
92+
// Number of FTM frames requested in terms of 4 or 8 bursts (allowed values - 0 (No pref), 16, 24, 32, 64)
93+
94+
and
95+
96+
.. code-block:: arduino
97+
98+
const char * WIFI_FTM_SSID = "WiFi_FTM_Responder"; // SSID of AP that has FTM Enabled
99+
const char * WIFI_FTM_PASS = "ftm_responder"; // STA Password
100+
101+
Testing
102+
*******
103+
104+
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.
105+
106+
**Example**
107+
108+
.. code-block:: arduino
109+
110+
/*
111+
THIS FEATURE IS SUPPORTED ONLY BY ESP32-S2 AND ESP32-C3
112+
*/
113+
114+
and
115+
116+
.. code-block:: markdown
117+
118+
Currently, this example supports the following targets.
119+
120+
| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 |
121+
| ----------------- | ----- | -------- | -------- | -------- |
122+
123+
Example Template
124+
****************
125+
126+
The example template can be found `here <https://github.com/espressif/arduino-esp32/tree/master/libraries/ESP32/examples/Template/ExampleTemplate>`_ and can be used as a reference.
127+
42128
Legal Part
43129
----------
44130

45131
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.
46132

47-
48-
49133
.. _Arduino style guide: https://www.arduino.cc/en/Reference/StyleGuide

‎libraries/ESP32/examples/Template/ExampleTemplate/ExampleTemplate.ino

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/* Arduino Example Template
2+
3+
This example code is in the Public Domain (or CC0 licensed, at your option.)
4+
5+
Unless required by applicable law or agreed to in writing, this
6+
software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
7+
CONDITIONS OF ANY KIND, either express or implied.
8+
*/
9+
10+
void setup() {
11+
12+
}
13+
14+
void loop() {
15+
16+
}

‎docs/EXAMPLE_README_TEMPLATE.md renamed to ‎libraries/ESP32/examples/Template/ExampleTemplate/README.md

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Arduino-ESP32 Example/Library Name ==(REQUIRED)==
22

3-
==*Add a brief description about this example/library here!*==
3+
==*Add a brief description of this example/library here!*==
44

55
This example/library demonstrates how to create a new example README file.
66

@@ -15,33 +15,33 @@ Currently, this example supports the following targets.
1515

1616
## How to Use Example/Library ==(OPTIONAL)==
1717

18-
==*Add a brief description on how to use this example.*==
18+
==*Add a brief description of how to use this example.*==
1919

2020
* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide).
2121

2222
### Hardware Connection ==(OPTIONAL)==
2323

24-
==*Add a brief description about wiring or any other hardware specific connection.*==
24+
==*Add a brief description of wiring or any other hardware-specific connection.*==
2525

2626
To use this example, you need to connect the LED to the `GPIOx`.
2727

2828
SDCard GPIO connection scheme:
2929

30-
| SDCard Pin | Function | GPIO |
30+
| SDCard Pin | Function | GPIO |
3131
| ----------- | -------- | ------ |
32-
| 1 | CS | GPIO5 |
33-
| 2 | DI/MOSI | GPIO23 |
34-
| 3 | VSS/GND | GND |
35-
| 4 | VDD/3V3 | 3V3 |
36-
| 5 | SCLK | GPIO18 |
37-
| 6 | VSS/GND | GND |
38-
| 7 | DO/MISO | GPIO19 |
32+
| 1 | CS | GPIO5 |
33+
| 2 | DI/MOSI | GPIO23 |
34+
| 3 | VSS/GND | GND |
35+
| 4 | VDD/3V3 | 3V3 |
36+
| 5 | SCLK | GPIO18 |
37+
| 6 | VSS/GND | GND |
38+
| 7 | DO/MISO | GPIO19 |
3939

4040
To add images, please create a folder `_asset` inside the example folder to add the relevant images.
4141

4242
### Configure the Project ==(OPTIONAL)==
4343

44-
==*Add a brief description about this example here!*==
44+
==*Add a brief description of this example here!*==
4545

4646
Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`.
4747

@@ -66,7 +66,7 @@ To get more information about the Espressif boards see [Espressif Development Ki
6666

6767
#### Using Platform IO
6868

69-
* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file.
69+
* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file.
7070

7171
## Example/Log Output ==(OPTIONAL)==
7272

@@ -98,21 +98,21 @@ Chip ID: 3957392
9898
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed.
9999
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation.
100100

101-
If the error persist, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
101+
If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
102102

103103
## Contribute ==(REQUIRED)==
104104

105-
==*Do not change! Keep as is.*==
105+
==*Do not change! Keep it as is.*==
106106

107107
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
108108

109109
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!
110110

111-
Before creating a new issue, be sure to try the Troubleshooting and to check if the same issue was already created by someone else.
111+
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
112112

113113
## Resources ==(REQUIRED)==
114114

115-
==*Do not change here! Keep as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*==
115+
==*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*==
116116

117117
* Official ESP32 Forum: [Link](https://esp32.com)
118118
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)

0 commit comments

Comments
 (0)