From d034c6144c4d1f4f6427030cf74ffd9d630850ee Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Wed, 22 Jan 2020 00:15:57 +0100
Subject: [PATCH] :books: Add assertion documentation.

---
 docs/04-Common-Guide.md                       | 52 +++++++++++++++++++
 ...oyment-Guide.md => 05-Deployment-Guide.md} |  0
 2 files changed, 52 insertions(+)
 create mode 100644 docs/04-Common-Guide.md
 rename docs/{04-Deployment-Guide.md => 05-Deployment-Guide.md} (100%)

diff --git a/docs/04-Common-Guide.md b/docs/04-Common-Guide.md
new file mode 100644
index 0000000000..dfc5c4875c
--- /dev/null
+++ b/docs/04-Common-Guide.md
@@ -0,0 +1,52 @@
+# Common's guide #
+
+This section intends to have articles that related to both frontend
+and backend, such as: code style hints, architecture dicisions, etc...
+
+
+## Assertions ##
+
+UXBOX source code has 3 types of assertions that can be used: simple,
+spec, and dev-spec.
+
+The simple assertion consists in using the clojure builting `assert`
+macro. This asserts are only executed on development mode. On
+production environment all assets like this will be ignored by
+runtime.
+
+Example:
+
+```clojure
+(assert (number? 3) "optional message")
+```
+
+Also, if you are using clojure.spec, you have the spec based
+`clojure.spec.alpha/assert` macro. In the same way as the
+`clojure.core/assert`, on production environment this asserts will be
+removed by the compiler/runtime.
+
+Example:
+
+````clojure
+(require '[clojure.spec.alpha :as s])
+
+(s/def ::number number?)
+
+(s/assert ::number 3)
+```
+
+And finally, for cases when you want a permanent assert (including in
+production code), you need to use `uxbox.common.spec/assert` macro. It
+has the same call signature as `clojure.spec.alpha/assert`.
+
+Example:
+
+```clojure
+(require '[uxbox.common.spec :as us])
+
+(us/assert ::number 3)
+```
+
+This macro enables you have assetions on production code.
+
+
diff --git a/docs/04-Deployment-Guide.md b/docs/05-Deployment-Guide.md
similarity index 100%
rename from docs/04-Deployment-Guide.md
rename to docs/05-Deployment-Guide.md