From 473e610490a72ad43f981b5b770f74d8e8788734 Mon Sep 17 00:00:00 2001
From: Mathieu Carbou <mathieu.carbou@gmail.com>
Date: Sun, 23 Jun 2024 12:30:41 +0200
Subject: [PATCH] Update doc and issue templates

---
 .github/ISSUE_TEMPLATE/bug_report.md | 33 ++++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/question.md   | 10 +++++++++
 README.md                            | 29 +++++++++++++++++-------
 docs/index.md                        | 29 +++++++++++++++++-------
 4 files changed, 85 insertions(+), 16 deletions(-)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/question.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..361e6fa
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: "[BUG]"
+labels: bug
+assignees: ''
+
+---
+
+**Please make sure to go through the recommendations before opening a bug report:**
+
+[https://github.com/mathieucarbou/ESPAsyncWebServer?tab=readme-ov-file#important-recommendations](https://github.com/mathieucarbou/ESPAsyncWebServer?tab=readme-ov-file#important-recommendations)
+
+**Description**
+
+A clear and concise description of what the bug is.
+
+**Board**
+
+esp32dev, esp32s3, etc
+
+**Ethernet adpater used ?**
+
+If yes, please specify which one
+
+**Stack trace**
+
+Please provide the stack trace here taken with `monitor_filters = esp32_exception_decoder`.
+**Any issue opened with a non readable stack trace will be ignored because not helpful at all.**
+
+**Additional notes**
+
+Add any other context about the problem here.
diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md
new file mode 100644
index 0000000..634179c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/question.md
@@ -0,0 +1,10 @@
+---
+name: Question
+about: Describe your question
+title: "[Q]"
+labels: question
+assignees: ''
+
+---
+
+
diff --git a/README.md b/README.md
index eb3a3cc..2c7ac66 100644
--- a/README.md
+++ b/README.md
@@ -86,17 +86,30 @@ void send(JsonDocument& doc) {
 
 I recommend to use the official API `AsyncWebSocketMessageBuffer` to retain further compatibility.
 
-## Stack size and queues
+## Important recommendations
 
-Here are some important flags to tweak depending on your needs:
+Most of the crashes are caused by improper configuration of the library for the project.
+Here are some recommendations to avoid them.
 
-```cpp
-  // Async TCP queue size
+1. Set the running core to be on the same core of your application (usually core 1) `-D CONFIG_ASYNC_TCP_RUNNING_CORE=1`
+2. Set the stack size appropriately with `-D CONFIG_ASYNC_TCP_STACK_SIZE=16384`.
+   The default value of `16384` might be too much for your project.
+   You can look at the [MycilaTaskMonitor](https://oss.carbou.me/MycilaTaskMonitor) project to monitor the stack usage.
+3. You can change **if you know what you are doing** the task priority with `-D CONFIG_ASYNC_TCP_PRIORITY=10`.
+   Default is `10`.
+4. You can increase the queue size with `-D CONFIG_ASYNC_TCP_QUEUE_SIZE=128`.
+   Default is `64`.
+5. You can decrease the maximum ack time `-D CONFIG_ASYNC_TCP_MAX_ACK_TIME=3000`.
+   Default is `5000`.
+
+I personally use the following configuration in my projects because my WS messages can be big (up to 4k).
+If you have smaller messages, you can increase `WS_MAX_QUEUED_MESSAGES` to 128.
+
+```c++
+  -D CONFIG_ASYNC_TCP_MAX_ACK_TIME=3000
+  -D CONFIG_ASYNC_TCP_PRIORITY=10
   -D CONFIG_ASYNC_TCP_QUEUE_SIZE=128
-  // Async TCP async task core
   -D CONFIG_ASYNC_TCP_RUNNING_CORE=1
-  // Async TCP async stac ksize
-  -D CONFIG_ASYNC_TCP_STACK_SIZE=8096
-  // WebSocket queue size
+  -D CONFIG_ASYNC_TCP_STACK_SIZE=4096
   -D WS_MAX_QUEUED_MESSAGES=64
 ```
diff --git a/docs/index.md b/docs/index.md
index eb3a3cc..2c7ac66 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -86,17 +86,30 @@ void send(JsonDocument& doc) {
 
 I recommend to use the official API `AsyncWebSocketMessageBuffer` to retain further compatibility.
 
-## Stack size and queues
+## Important recommendations
 
-Here are some important flags to tweak depending on your needs:
+Most of the crashes are caused by improper configuration of the library for the project.
+Here are some recommendations to avoid them.
 
-```cpp
-  // Async TCP queue size
+1. Set the running core to be on the same core of your application (usually core 1) `-D CONFIG_ASYNC_TCP_RUNNING_CORE=1`
+2. Set the stack size appropriately with `-D CONFIG_ASYNC_TCP_STACK_SIZE=16384`.
+   The default value of `16384` might be too much for your project.
+   You can look at the [MycilaTaskMonitor](https://oss.carbou.me/MycilaTaskMonitor) project to monitor the stack usage.
+3. You can change **if you know what you are doing** the task priority with `-D CONFIG_ASYNC_TCP_PRIORITY=10`.
+   Default is `10`.
+4. You can increase the queue size with `-D CONFIG_ASYNC_TCP_QUEUE_SIZE=128`.
+   Default is `64`.
+5. You can decrease the maximum ack time `-D CONFIG_ASYNC_TCP_MAX_ACK_TIME=3000`.
+   Default is `5000`.
+
+I personally use the following configuration in my projects because my WS messages can be big (up to 4k).
+If you have smaller messages, you can increase `WS_MAX_QUEUED_MESSAGES` to 128.
+
+```c++
+  -D CONFIG_ASYNC_TCP_MAX_ACK_TIME=3000
+  -D CONFIG_ASYNC_TCP_PRIORITY=10
   -D CONFIG_ASYNC_TCP_QUEUE_SIZE=128
-  // Async TCP async task core
   -D CONFIG_ASYNC_TCP_RUNNING_CORE=1
-  // Async TCP async stac ksize
-  -D CONFIG_ASYNC_TCP_STACK_SIZE=8096
-  // WebSocket queue size
+  -D CONFIG_ASYNC_TCP_STACK_SIZE=4096
   -D WS_MAX_QUEUED_MESSAGES=64
 ```