From 8b4a726d2d1f6f81c3b30872195e35aee9cd5aad Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axilleas@axilleas.me>
Date: Thu, 27 Apr 2017 14:21:44 +0200
Subject: [PATCH] Document the process of docs only changes

---
 .gitlab-ci.yml                           |  7 ++++---
 doc/development/writing_documentation.md | 24 ++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e30dd93e860..e911d7e5b89 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -68,11 +68,12 @@ stages:
     - //@gitlab-org/gitlab-ee
     - //@gitlab/gitlab-ee
 
-# Skip all jobs except the ones that begin with 'docs/', for commits
-# including ONLY doc changes inside the 'doc/` directory.
+# Skip all jobs except the ones that begin with 'docs/'.
+# Used for commits including ONLY documentation changes.
+# https://docs.gitlab.com/ce/development/writing_documentation.html#testing
 .except-docs: &except-docs
   except:
-    - /^docs\/*/
+    - /^docs\/.*/
 
 .rspec-knapsack: &rspec-knapsack
   stage: test
diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 166a10293c3..2814c18e0b6 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -70,3 +70,27 @@ All the docs follow the same [styleguide](doc_styleguide.md).
 ### Markdown
 
 Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future.
+
+## Testing
+
+We try to treat documentation as code, thus have implemented some testing.
+Currently, the following tests are in place:
+
+1. `docs:check:links`: Check that all internal (relative) links work correctly
+1. `docs:check:apilint`: Check that the API docs follow some conventions
+
+If your contribution contains **only** documentation changes, you can speed up
+the CI process by prepending to the name of your branch: `docs/`. For example,
+a valid name would be `docs/update-api-issues` and it will run only the docs
+tests. If the name is `docs-update-api-issues`, the whole test suite will run
+(including docs).
+
+---
+
+When you submit a merge request to GitLab Community Edition (CE), there is an
+additional job called `rake ee_compat_check` that runs against Enterprise
+Edition (EE) and checks if your changes can apply cleanly to the EE codebase.
+If that job fails, read the instructions in the job log for what to do next.
+Contributors do not need to submit their changes to EE, GitLab Inc. employees
+on the other hand need to make sure that their changes apply cleanly to both
+CE and EE.