From 8c1a26697a340c8bae3a2b6445818656bf09f47c Mon Sep 17 00:00:00 2001
From: Stepan Strelets <s.strelec@nikitaonline.ru>
Date: Sun, 26 Mar 2017 00:59:39 +0300
Subject: [PATCH] Add environment documentation

---
 docs/en/README.md       |  1 +
 docs/en/environments.md | 47 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 docs/en/environments.md

diff --git a/docs/en/README.md b/docs/en/README.md
index d8bbffe9..41d729a2 100644
--- a/docs/en/README.md
+++ b/docs/en/README.md
@@ -23,6 +23,7 @@ Using PHP Censor
     * [Git](sources/git.md)
 * [Injecting variables into messages](interpolation.md)
 * [Project Status Images and Status Page](status.md)
+* [Build environments](environments.md)
 
 Plugins
 -------
diff --git a/docs/en/environments.md b/docs/en/environments.md
new file mode 100644
index 00000000..8925cec0
--- /dev/null
+++ b/docs/en/environments.md
@@ -0,0 +1,47 @@
+Environments
+============
+
+A environment can include several branches - base branch (default project branch) and optional additional branches (which merge into base).
+
+When you commit to a branch, builds all environments in which branch included (base branch implicitly included to all environments).
+
+When you build a environment, additional branches merged into base branch.
+
+For example, it can be useful when yoy dealy merging into master or test some branches at once. Or deploy. 
+
+Config example and explanation
+------------------------------
+Configuration is specified on project edit page.
+
+In this example, there are three environments:
+* Production (named `pr`) is associated with the default branch for the project.
+* Release candidate (`rc`) - branch by default plus branch `feature-A`
+* Test (`test`) - branch by default plus branch `feature-B`
+
+```yml
+pr:
+rc:
+    - feature-A
+test:
+    - feature-B
+```
+
+When you push commits to `master` branch, three builds will be created - one for each of the environments.
+ 
+If push commit to branch `feature-A` - build for `rc` environment will be created.
+
+If push commit to branch `feature-C` - no build will be created.
+
+You can use variable `%ENVIRONMENT%` in project config.
+
+```yml
+setup:
+  mysql:
+    - "DROP DATABASE IF EXISTS project_name_%ENVIRONMENT%;"
+    - "CREATE DATABASE project_name_%ENVIRONMENT%;"
+test:
+    ...
+deploy:
+    mage:
+        env: %ENVIRONMENT%
+```