You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document describes rules that are in effect for this repository, meant for handling issues by contributors in the issue tracker and PRs.
2
+
# Opening New Issues
3
+
1. The issue tracker is precisely that: a tool to track issues in the core code, and not a discussion forum. Opening an issue means that a problem has been found in the core code, and that it should be addressed by a contributor.
4
+
2. When opening an issue, a template is presented with fields to fill out. The requested information is important. If the template is ignored, or not enough info about the issue is provided, the issue may be closed due to lack of info. Example:
5
+
* Using WifiMulti and FS crashes with error. Why? (no basic info, no IDE settings, no sketch provided)
6
+
3. Questions of type "How do I..." or "Can you please help me with..." or "Can the ESP do..." won't be handled here. Such questions should be directed at a discussion forum, like esp8266.com or stackoverflow. All issues of this type will be closed with a simple reference to the policy. Example:
7
+
* how do I connect to wifi
8
+
* how do I connect two ESPs
9
+
* can I send http data over a public network
10
+
* my wiring/project/code doesn't work, help!
11
+
4. Issues that are obviously user error, programming language errors, lack of knowledge or experience with the use semantics of the core libs, or similar, will be closed with a reference to the policy. Examples:
12
+
* sketch crashes due to a char[] in it that is not null terminated
13
+
* trying to use yield/delay, or libs that use yield/delay, from inside async callbacks
14
+
* Use of new/malloc without matching delete/free (mem leak)
15
+
5. Issues about topics already handled in the documentation will be closed in a similar manner. Example:
16
+
* can't flash with error espcomm failed
17
+
6. Issues must be provided with a minimalist sketch. Issues with an incomplete sketch, or a huge sketch, will be closed. Maximum effort must be put forth by the person opening the issue to reduce the relevant code that reproduces the issue, so that investigation can be taken up. MCVE is a must.
18
+
7. Issues for unmerged PRs will be closed. If there is an issue with a PR, the explanation should be added to the PR itself.
19
+
8. Issues with accompanied investigation that shows the root of the problem should be given priority
20
+
9. Duplicate issues will be closed with a reference to the original
21
+
22
+
# Triaging
23
+
1. Any contributor of the project can participate in the triaging process, if he/she chooses to do so
24
+
2. An issue that needs to be closed, either due to not complying with this policy, or for other reasons, should be closed by a contributor
25
+
3. Issues that are accepted should be marked with appropriate labels, e.g.: component: xyz
26
+
4. If an issue is deemed to require specialized knowledge (e.g.: TLS, HTTP parser, SDK integration, etc), contributor(s) relevant to the affected code should be /cc’ed, as this can help grab attention
27
+
5. Severe issues should be assigned to the current milestone (i.e.: the next version to be released), or the milestone following. It is ok to push back issues depending on available resources.
28
+
6. Issues that could impact functionality for many users should be considered severe.
29
+
7. Issues caused by the SDK or chip should not be marked severe, as there usually isn’t much to be done. Common sense should be applied when deciding. Such issues should be documented in a KID (Known Issues Document), possibly on the Wiki, for reference by users. Example:
30
+
* ARP issue
31
+
* Extra channel change beacon announced by the SoftAP
32
+
* Wakeup ROM bug in the ESP chip
33
+
8. Issues with feature requests should be discussed for viability/desirability. Example:
34
+
* Support for new board. If the new board is not widely used, doesn’t have a manufacturer webpage, etc, then it isn’t desirable to support it. If the new board is essentially a duplicate of another, it isn’t desirable to duplicate the existing one.
35
+
9. Feature requests or changes that are meant to address a very specific/limited use case, especially if at the expense of increased code complexity, may be denied, or may be required to be redesigned, generalized, or simplified
36
+
10. Feature requests that are not accompanied by a PR:
37
+
* could be closed immediately (denied)
38
+
* could be closed after some predetermined period of time (left as candidate for somebody to pick up)
39
+
* could be deemed interesting enough to work on, but without a specific project or target, and hence accumulated in a long-term feature request list. Such feature requests will in general not be targeted for a deadline or release.
40
+
11. In some cases, feedback may be requested from the issue reporter, either as additional info for clarification, additional testing, or other. If no feedback is provided after 30 days, the issue may be closed by a contributor.
41
+
42
+
# Compatibility
43
+
1. Compatibility with the Arduino build system is first priority. Compatibility with PlatformIO and make are also maintained, but are second priority.
44
+
2. Feature requests should consider compatibility with Arduino
45
+
* ESP-specific APIs should be added with care, and should be marked as such (Example: ESP8266WiFi)
46
+
* APIs of common libraries should maintain compatibility (Example: Wire, SPI, Servo)
47
+
* ESP-specific extensions to compatible APIs are ok, especially if required to fully use certain peripherals, but such functions should be clearly marked as ESP-specific
48
+
3. When making changes that are likely to impact PlatformIO or make, relevant people should be notified. Check whether some corresponding changes are needed on the build system side. When an issue related to one of these build systems is reported, redirect the issue reporter to the respective issue tracker.
49
+
4. The core libs are implemented as a wrapper layer over the Espressif SDK. Due to the requirements and limitations imposed by the SDK, there are inherent differences between the behavior of this core and the standard Arduino core (Example: using long delay()s is not allowed here). Compatibility can’t be maintained in such cases, and differences should be clearly documented.
50
+
51
+
# Pull requests
52
+
1. All pull requests should undergo peer review by at least one contributor other than the creator
53
+
2. All pull requests should consider updates to the documentation
54
+
3. All pull requests should consider updates to regression tests, where possible
55
+
4. Pull requests that address an outstanding issue, particularly an issue deemed to be severe, should be given priority
56
+
5. If a PR is accepted, then it should undergo review and updated based on the feedback provided, then merged
57
+
6. Pull requests that don't meet the above will be denied and closed
58
+
59
+
# Other
60
+
A table should be maintained for relating maintainers and components. When triaging, this is essential to figure out if someone in particular should be consulted about specific changes.
61
+
62
+
A stable release cadence should be established, e.g.: every 6 months.
63
+
64
+
Regression testing should be revisited and streamlined with the release process. Running regression tests should be done before merging a PR to reduce overhead for a release.
Copy file name to clipboardExpand all lines: README.md
+33-43Lines changed: 33 additions & 43 deletions
Original file line number
Diff line number
Diff line change
@@ -5,8 +5,6 @@ This project brings support for ESP8266 chip to the Arduino environment. It lets
5
5
6
6
ESP8266 Arduino core comes with libraries to communicate over WiFi using TCP and UDP, set up HTTP, mDNS, SSDP, and DNS servers, do OTA updates, use a file system in flash memory, work with SD cards, servos, SPI and I2C peripherals.
7
7
8
-
A large community is well established for questions and answers about Arduino for ESP8266 [ESP8266 Community Forum](http://www.esp8266.com/u/arduinoanswers)
@@ -18,35 +16,24 @@ A large community is well established for questions and answers about Arduino fo
18
16
-[Contributing](#contributing)
19
17
-[License and credits](#license-and-credits)
20
18
21
-
### Installing with Boards Manager ###
19
+
### Installing with Boards Manager
22
20
23
21
Starting with 1.6.4, Arduino allows installation of third-party platform packages using Boards Manager. We have packages available for Windows, Mac OS, and Linux (32 and 64 bit).
24
22
25
-
- Install Arduino 1.6.8 from the [Arduino website](http://www.arduino.cc/en/main/software).
23
+
- Install the current upstream Arduino IDE at the 1.8 level or later. The current version is at the [Arduino website](http://www.arduino.cc/en/main/software).
26
24
- Start Arduino and open Preferences window.
27
25
- Enter ```http://arduino.esp8266.com/stable/package_esp8266com_index.json``` into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
28
26
- Open Boards Manager from Tools > Board menu and install *esp8266* platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation).
29
27
30
-
The best place to ask questions related to this core is ESP8266 community forum: http://www.esp8266.com/arduino.
31
-
If you find this forum or the ESP8266 Boards Manager package useful, please consider supporting it with a donation. <br />
-Quick Start with [PlatformIO IDE](http://docs.platformio.org/page/ide/atom.html#quick-start) or [PlatformIO Core](http://docs.platformio.org/page/core.html)
@@ -85,30 +72,33 @@ Using make instead of the Arduino IDE makes it easier to do automated and produc
85
72
86
73
### Documentation
87
74
88
-
Documentation for latest development version:
89
-
90
-
-[Reference](doc/reference.md)
91
-
-[Libraries](doc/libraries.md)
92
-
-[File system](doc/filesystem.md)
93
-
-[OTA update](doc/ota_updates/readme.md)
94
-
-[Supported boards](doc/boards.md)
95
-
-[FAQ / Trubleshooting](doc/faq/readme.md)
96
-
-[Change log](doc/changes.md)
75
+
Documentation for latest development version: https://arduino-esp8266.readthedocs.io/en/latest/
97
76
98
77
### Issues and support ###
99
78
100
-
If you encounter an issue, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues.
101
-
Please provide as much context as possible: version which you are using (you can check it in Boards Manager), your sketch code, serial output, board model, IDE settings (board selection, flash size, etc).
79
+
[ESP8266 Community Forum](http://www.esp8266.com/u/arduinoanswers) is a well established community for questions and answers about Arduino for ESP8266.
80
+
81
+
If you find this forum useful, please consider supporting it with a donation. <br />
If you encounter an issue which you think is a bug in the ESP8266 Arduino Core or the associated libraries, you are welcome to submit it here on Github: https://github.com/esp8266/Arduino/issues.
85
+
86
+
Please provide as much context as possible:
102
87
103
-
If you can not find the answers above, you can also try [ESP8266 Community Forum](http://www.esp8266.com/arduino)
88
+
- ESP8266 Arduino core version which you are using (you can check it in Boards Manager)
89
+
- your sketch code; please wrap it into a code block, see [Github markdown manual](https://help.github.com/articles/basic-writing-and-formatting-syntax/#quoting-code)
90
+
- when encountering an issue which happens at run time, attach serial output. Wrap it into a code block, just like the code.
91
+
- for issues which happen at compile time, enable verbose compiler output in the IDE preferences, and attach that output (also inside a code block)
92
+
- ESP8266 development board model
93
+
- IDE settings (board choich, flash size)
104
94
105
95
### Contributing
106
96
107
-
For minor fixes of code and documentation, go ahead and submit a pull request.
97
+
For minor fixes of code and documentation, please go ahead and submit a pull request.
108
98
109
-
Check out the list of issues which are easy to fix — [easy issues for 2.2.0](https://github.com/esp8266/Arduino/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.2.0+label%3A%22level%3A+easy%22). Working on them is a great way to move the project forward.
99
+
Check out the list of issues which are easy to fix — [easy issues for 2.5.0](https://github.com/esp8266/Arduino/issues?q=is%3Aopen+is%3Aissue+milestone%3A2.5.0+label%3A%22level%3A+easy%22). Working on them is a great way to move the project forward.
110
100
111
-
Larger changes (rewriting parts of existing code from scratch, adding new functions to the core, adding new libraries) should generally be discussed [in the chat](https://gitter.im/esp8266/Arduino) first.
101
+
Larger changes (rewriting parts of existing code from scratch, adding new functions to the core, adding new libraries) should generally be discussed by opening an issue first.
112
102
113
103
Feature branches with lots of small commits (especially titled "oops", "fix typo", "forgot to add file", etc.) should be squashed before opening a pull request. At the same time, please refrain from putting multiple unrelated changes into a single pull request.
0 commit comments