Add tutorial about flaky tests

Author: adpi2

_overviews/toolkit/munit-flakiness.md

@@ -1,15 +1,57 @@
 ---
 title: How to deal with flaky tests?
 type: section
-description: ???
+description: Describe the flaky tag in MUnit.
 num: 10
 previous-page: munit-resources
 next-page: munit-assumptions
 ---
 
 {% include markdown.html path="_markdown/install-munit.md" %}
 
-<!-- Tutorial about the `.flaky` tag and how to configure the `MUNIT_FLAKY_OK` environment variable in the CI. 
+A flaky test is a test that fails randomly depending on some outside factor: network issue, concurrency issue, high memory or CPU usage.
+The problem with flaky test is that it makes your CI fails regardless of the actual changes in the code.
 
-See https://scalameta.org/munit/docs/tests.html#tag-flaky-tests
--->
+As a first step you should try to fix the flaky test.
+However, it is sometimes hard to stabilize a test, and yet it is better to keep it than to remove it.
+
+In MUnit you can flag a flaky test with `.flaky`.
+
+{% tabs 'flaky-1' class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+class MyTests extends munit.FunSuite {
+  test("send some request".flaky) {
+    // body of the test
+  }
+}
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+class MyTests extends munit.FunSuite:
+  test("send some request".flaky) {
+    // body of the test
+  }
+```
+{% endtab %}
+{% endtabs %}
+
+
+In your CI you can set the `MUNIT_FLAKY_OK` environment variable to true to ignore the failure of the flaky tests.
+
+{% tabs 'flaky-2' class=tabs-ci %}
+{% tab 'Github Action' %}
+In a Github action this is how you can set `MUNIT_FLAKY_OK`.
+
+```yaml
+env:
+  MUNIT_FLAKY_OK: true
+```
+{% endtab %}
+{% endtabs %}
+
+The CI will pass even if the flaky test fails.
+
+Beware not to abuse the flaky tag, as it can make your tests fail silently because of a regression in your code.
+To avoid this you should, once in while, run the flaky tests locally, or without the `MUNIT_FLAKY_OK`.