Merge branch 'improve_docs' into 'master'

Jobs documentation

See merge request !149

4 files changed, 61 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index 9892d6f..10098e0 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -4,3 +4,4 @@
 + [Examples](examples/README.md)
 + [Install](install/installation.md)
 + [Update](update/README.md)
++ [Jobs](jobs/README.md)
diff --git a/doc/jobs/README.md b/doc/jobs/README.md
new file mode 100644
index 0000000..ab98e0e
--- /dev/null
+++ b/doc/jobs/README.md
@@ -0,0 +1,60 @@
+# Jobs
+
+Jobs are user-created shell scripts. On each push to GitLab the CI creates builds for each job.
+Every build is served by runners on which the shell scripts from these jobs are ran.
+There are two types of jobs: test jobs (ran in parallel) and deploy jobs (ran on success).
+
+### Test job (run in parallel)
+
+![Jobs](job.png)
+
+These kind of jobs run in parallel and can be useful for test suites.
+For example, to save time you can run one part of your test suite in one build
+and a second part in another build.
+
+Fields:
+
+`name` - an arbitrary name of a job
+
+`builds commit` (checkbox) - check this if you want to create a build on
+pushes of regular commits and branches
+
+`build tag` (checkbox) - check this if you want to start a build on each tag pushed
+
+_For example, for GitLab we created a job for building packages. We want packages to be built when we push
+new tags. So what we did is disable `builds commit` and we enabled `build tag`._
+
+`tags` - the list of tags (ex. "ruby mysql silenium"), only runners that contain the same set of tags can perform this build.
+
+Script - your shell script to run. Example for rails projects:
+
+```
+export PATH=~/bin:/usr/local/bin:/usr/bin:/bin
+gem install bundler
+cp config/database.yml.mysql config/database.yml
+cp config/application.yml.example config/application.yml
+bundle
+RAILS_ENV=test bundle exec rake db:setup
+RAILS_ENV=test bundle exec rake spec
+```
+
+
+### Deploy jobs (ran on success)
+
+![Deploy jobs](deploy_job.png)
+
+This type of jobs runs after all test jobs pass.
+It is especially useful for deploying applications.
+For example, if you want to make sure that whole test suite passes before each deploy.
+
+Fields:
+
+`name` - an arbitrary name of the deploy job
+
+`tags` - Just like test jobs, you probably have a specific runner in mind
+that can deploy your code, as this runner needs special permissions, for instance.
+Here you can set the tags for the runners that are allowed to run the deploy job.
+
+`refs` - Here you can specify git refs that should trigger a deploy job
+
+`script` - The actual shell script to run.
diff --git a/doc/jobs/deploy_job.png b/doc/jobs/deploy_job.png
new file mode 100644
index 0000000..f940710
--- /dev/null
+++ b/doc/jobs/deploy_job.png
diff --git a/doc/jobs/job.png b/doc/jobs/job.png
new file mode 100644
index 0000000..760d107
--- /dev/null
+++ b/doc/jobs/job.png