add docs guidelines: cherry-picking commits from CE to EE

1 files changed, 101 insertions, 0 deletions

diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md
index 403c9d08752..c7827679745 100644
--- a/doc/development/writing_documentation.md
+++ b/doc/development/writing_documentation.md
@@ -27,6 +27,8 @@ is documented.
 
 Whenever you submit a merge request for the documentation, use the documentation MR description template.
 
+Please check the [documentation workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/) before getting started.
+
 ### Documentation directory structure
 
 The documentation is structured based on the GitLab UI structure itself,
@@ -116,6 +118,105 @@ choices:
 If your branch name matches any of the above, it will run only the docs
 tests. If it doesn't, the whole test suite will run (including docs).
 
+### Merge requests for GitLab documentation
+
+Before getting started, please make sure you read the introductory section
+"[contributing to docs](#contributing-to-docs)" above and the
+[tech writing workflow](https://about.gitlab.com/handbook/product/technical-writing/workflow/)
+for GitLab Team members.
+
+- Please use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md)
+- Please use the correct [branch name](#branch-naming)
+- Label the MR `Documentation`
+- Assign the correct milestone (see note below)
+
+> Note:
+>
+> If the release version you want to add the documentation to has already been
+frozen or released, please use the label `Pick into X.Y` to get it merged into
+the correct release. Avoid picking into a past release as much as you can, as
+it increases the work of the release managers.
+
+#### Cherry-picking from CE to EE
+
+As we have the `master` branch of CE merged into EE once a day, it's common to
+run into merge conflicts. To avoid them, we [test for merge conflicts against EE](#testing)
+with the `ee-compat-check` job, and use the following method of creating equivalent
+branches for CE and EE.
+
+This method only requires that you have cloned both CE and EE into your computer:
+
+- Clone CE repo: `git clone git@gitlab.com:gitlab-org/gitlab-ce.git`
+- Clone EE repo: `git clone git@gitlab.com:gitlab-org/gitlab-ee.git`
+
+And the only additional setup we need is to add CE as remote of EE and vice-versa:
+
+- Open two terminal windows, one in CE, and another one in EE:
+  - In EE: `git remote add ce git@gitlab.com:gitlab-org/gitlab-ce.git`
+  - In CE: `git remote add ee git@gitlab.com:gitlab-org/gitlab-ee.git`
+
+That's all setup we need, so that we can cherry-pick a commit from CE to EE, and
+from EE to CE.
+
+Now, every time you create an MR for the docs:
+
+1. Open two terminal windows, one in CE, and another one in EE
+1. In the CE terminal:
+  1. Create the [CE branch](#branch-naming) starting with `docs-`,
+  e.g.: `git checkout -b docs-example`
+  1. Make your changes and push a commit (commit A)
+  1. Create the merge request in GitLab
+1. In the EE terminal:
+  1. Create the EE-equivalent branch ending with `-ee`, e.g.,
+  `git checkout -b docs-example-ee`
+  1. Fetch the CE branch: `git fetch ce docs-example`
+  1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA`
+  1. If Git prompts you to fix the conflicts, do a `git status`
+  to check which files contain conflicts, fix them, save the files
+  1. Add the changes with `git add .` but **DO NOT commit** them
+  1. Continue cherry-picking: `git cherry-pick --continue`
+  1. Push to EE: `git push origin docs-example-ee`
+1. Create the EE-equivalent MR and link to the CE MR from the
+description "Ports [CE-MR-LINK] to EE"
+1. Once all the jobs are passing in CE and EE, and you've addressed the
+feedback from your on team, assign the CE MR to a technical writer for review
+1. When both MRs are ready, the EE merge request will be merged first, and the
+CE-equivalent will be merged in the sequence.
+
+**Important notes:**
+
+- The commit SHA can be easily found from the GitLab UI. E.g., from a merge request,
+open the tab **Commits** and click the copy icon to copy the commit SHA.
+- To cherry-pick a **commit range**, such as [A > B > C > D] use:
+
+    ```shell
+    git cherry-pick "oldest-commit-SHA^..newest-commit-SHA"
+    ```
+
+    For example, suppose the commit A is the oldest, and its SHA is `4f5e4018c09ed797fdf446b3752f82e46f5af502`;
+    and the commit D is the newest, and its SHA is `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
+    The cherry-pick command will be:
+
+    ```shell
+    git cherry-pick "4f5e4018c09ed797fdf446b3752f82e46f5af502^..80e1c9e56783bd57bd7129828ec20b252ebc0538"
+    ```
+
+- To cherry-pick a **merge commit**, use the flag `-m 1`. For example, suppose that the
+merge commit SHA is `138f5e2f20289bb376caffa0303adb0cac859ce1`:
+
+    ```shell
+    git cherry-pick -m 1 138f5e2f20289bb376caffa0303adb0cac859ce1
+    ```
+
+- Note that the review will occur only in the CE MR, as we expect that the EE MR
+contains the same commits as the CE MR.
+- If you push more commits to the CE branch, you can safely repeat the procedure
+to cherry-pick them to EE.
+- If you have a few more changes that apply to the EE-version only, you can submit
+a couple more commits to the EE branch, but ask the reviewer to review the EE merge request
+additionally to the CE MR. If there are many EE-only changes, please start a new MR
+to EE only.
+
 ### Previewing the changes live
 
 If you want to preview the doc changes of your merge request live, you can use