From b9754a5b3e06ea5f2149f8a749e7cb8ccd2c3a46 Mon Sep 17 00:00:00 2001
From: Tobias Witek <git@witek.at>
Date: Thu, 18 Jun 2020 07:14:10 +0200
Subject: [PATCH] [docs] update

---
 README.md                    |  9 +++++++++
 docs/development/general.rst | 34 ++++++++++++++++++++++++++++++++++
 docs/development/index.rst   |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 docs/development/general.rst

diff --git a/README.md b/README.md
index 4983a21..2d97326 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,15 @@ Supported Python versions: 3.4, 3.5, 3.6, 3.7, 3.8
 
 Supported FontAwesome version: 4 (free version of 5 doesn't include some of the icons)
 
+---
+**NOTE**
+
+I am planning to rename `master` to `main` - the branch already exists, and I will eventually change the **default** branch to `main`. Just be advised :)
+
+If you are curious why: [ZDNet:github-master-alternative](https://www.zdnet.com/article/github-to-replace-master-with-alternative-term-to-avoid-slavery-references/)
+
+---
+
 Example usage:
 
 ```
diff --git a/docs/development/general.rst b/docs/development/general.rst
new file mode 100644
index 0000000..68c40d3
--- /dev/null
+++ b/docs/development/general.rst
@@ -0,0 +1,34 @@
+General guidelines
+==================
+
+Writing unit tests
+------------------
+
+Some general hints:
+
+- Tests should run with just Python Standard Library modules installed
+  (i.e. if there are additional requirements, the test should be skipped
+  if those are missing)
+- Tests should run even if there is no network connectivity (please mock
+  urllib calls, for example)
+- Tests should be stable and not require modifications every time the
+  tested code's implementation changes slightly (been there / done that)
+
+Right now, ``bumblebee-status`` is moving away from Python's
+built-in ``unittest`` framework (tests located inside ``tests/``)
+and towards ``pytest`` (tests located inside ``pytests/``).
+
+First implication: To run the new tests, you need to have ``pytest``
+installed, it is not part of the Python Standard Library. Most
+distributions call the package ``python-pytest`` or ``python3-pytest``
+or something similar (or you just use ``pip install --use pytest``)
+
+Aside from that, you just write you tests using ``pytest`` as usual,
+with one big caveat:
+
+**If** you create a new directory inside ``pytests/``, you need to
+also create a file called ``__init__.py`` inside that, otherwise,
+modules won't load correctly.
+
+For examples, just browse the existing code. A good, minimal sample
+for unit testing ``bumblebee-status`` is ``pytests/core/test_event.py``.
diff --git a/docs/development/index.rst b/docs/development/index.rst
index 3fc86fc..179dee0 100644
--- a/docs/development/index.rst
+++ b/docs/development/index.rst
@@ -5,6 +5,7 @@ Developer's Guide
    :maxdepth: 2
    :caption: Contents:
 
+   general
    module
    theme