From 162e5f3bcb04e1b0180073b2346e335de721a17f Mon Sep 17 00:00:00 2001
From: Michal Bocek <mbocek@redhat.com>
Date: Wed, 5 Dec 2018 19:16:27 +0100
Subject: [PATCH] Add best practices doc page

- partially moved from:
https://leapp.readthedocs.io/en/latest/best-practises.html
---
 docs/best-practices.md | 51 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/best-practices.md

diff --git a/docs/best-practices.md b/docs/best-practices.md
new file mode 100644
index 0000000000..c8ae2ed5cb
--- /dev/null
+++ b/docs/best-practices.md
@@ -0,0 +1,51 @@
+# Best practices for writing actors
+
+
+### Follow the Python Coding Guidelines
+
+See the [Python Coding Guidelines](CONTRIBUTING.md#coding-guidelines).
+
+### Avoid running the code on a module level
+
+Actors are completely written in Python, however, they are loaded beforehand to get all the meta-information from the actors.
+To avoid slow downs we ask actor writers not to execute any code that is not absolutely necessary on a module level.
+
+### Avoid global non Leapp imports
+
+Avoid importing system or bundled libraries on a module level. This again has to do with slow down, and also to avoid
+unnecessary complications for our tests automation which needs to inspect the actors beforehand.
+
+### Use the snactor tool
+
+Using the snactor tool provides you with all minimally necessary layouts of the repository, and creates
+things like topics and tags.
+
+It helps you with debugging, and it is able to execute individual actors. The snactor tool has also the ability to 
+discover all the entities in your current project repository, such as actors, models, tags, topics, and workflows.
+
+### Avoid writing generic actors
+
+Generic actors that are too abstract are usually a sign for code that should be part of the
+[Leapp Standard Library](https://github.com/oamg/leapp/tree/master/leapp/libraries/stdlib/) instead. Standard libraries
+help to reduce the complexity of the system, and the amount of actors that have to be scheduled and run.
+
+### Allow for unit testing
+Write all the actor’s logic in the actor’s library in order to be able to write unit tests for your functions separately.
+It is not currently possible to unit test any method or function in the actor.py. The only line in the actor.process()
+method then should be ideally just calling an entry point to the library. To create actor’s library, create new folder
+libraries in the actor’s folder and there create an arbitrarily named python file, e.g. library.py.
+
+myactor/actor.py:
+```
+from leapp.libraries.actor.library import do_the_actor_thingy
+class MyActor(Actor):
+    ...
+    def process(self):
+        do_the_actor_thingy(self)
+```
+
+myactor/libraries/library.py:
+```
+def do_the_actor_thingy(actor):
+    actor.log.debug("All the actor’s logic shall be outside actor.py")
+```