Merge branch 'docs-devguide-cherry-pick-ce-to-ee-ee' into 'master'

Docs guidelines: cherry-picking commits from CE to EE

See merge request gitlab-org/gitlab-ee!4729

doc/development/automatic_ce_ee_merge.md

@@ -103,6 +103,99 @@ Notes:
 - You can use [`git rerere`](https://git-scm.com/blog/2010/03/08/rerere.html)
   to avoid resolving the same conflicts multiple times.
 
+### Cherry-picking from CE to EE
+
+For avoiding merge conflicts, we use a method of creating equivalent branches
+for CE and EE. If the `ee-compat-check` job fails, this process is required.
+
+This method only requires that you have cloned both CE and EE into your computer.
+If you don't have them yet, please go ahead and clone them:
+
+- 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 CE and EE:
+
+1. Open two terminal windows, one in CE, and another one in EE
+1. In the CE terminal:
+  1. Create the CE branch, e.g., `branch-example`
+  1. Make your changes and push a commit (commit A)
+  1. Create the CE merge request in GitLab
+1. In the EE terminal:
+  1. Create the EE-equivalent branch ending with `-ee`, e.g.,
+  `git checkout -b branch-example-ee`
+  1. Fetch the CE branch: `git fetch ce branch-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 branch-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 both CE and EE, you've addressed the
+feedback from your own team, and got them approved, the merge requests can be merged.
+1. When both MRs are ready, the EE merge request will be merged first, and the
+CE-equivalent will be merged next.
+
+**Important notes:**
+
+- The commit SHA can be easily found from the GitLab UI. 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
+    ```
+- To cherry-pick multiple commits, such as B and D in a range [A > B > C > D], use:
+
+    ```shell
+    git cherry-pick commmit-B-SHA commit-D-SHA
+    ```
+
+    For example, suppose commit B SHA = `4f5e4018c09ed797fdf446b3752f82e46f5af502`,
+    and the commit D SHA = `80e1c9e56783bd57bd7129828ec20b252ebc0538`.
+    The cherry-pick command will be:
+
+    ```shell
+    git cherry-pick 4f5e4018c09ed797fdf446b3752f82e46f5af502 80e1c9e56783bd57bd7129828ec20b252ebc0538
+    ```
+
+    This case is particularly useful when you have a merge commit in a sequence of
+    commits and you want to cherry-pick all but the merge commit.
+
+- If you push more commits to the CE branch, you can safely repeat the procedure
+to cherry-pick them to the EE-equivalent branch. You can do that as many times as
+necessary, using the same CE and EE branches.
+- If you submitted the merge request to the CE repo and the `ee-compat-check` job passed,
+you are not required to submit the EE-equivalent MR, but it's still recommended. If the
+job failed, you are required to submit the EE MR so that you can fix the conflicts in EE
+before merging your changes into CE.
+
 ---
 
 [Return to Development documentation](README.md)

doc/development/writing_documentation.md

@@ -19,7 +19,7 @@ The one responsible for writing the first piece of documentation is the develope
 wrote the code. It's the job of the Product Manager to ensure all features are
 shipped with its docs, whether is a small or big change. At the pace GitLab evolves,
 this is the only way to keep the docs up-to-date. If you have any questions about it,
-please ask a Technical Writer. Otherwise, when your content is ready, assign one of
+ask a Technical Writer. Otherwise, when your content is ready, assign one of
 them to review it for you.
 
 We use the [monthly release blog post](https://about.gitlab.com/handbook/marketing/blog/release-posts/#monthly-releases) as a changelog checklist to ensure everything
@@ -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,
@@ -40,7 +42,7 @@ all docs should be linked. Every new document should be cross-linked to its rela
 
 The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have
 been deprecated and the majority their docs have been moved to their correct location
-in small iterations. Please don't create new docs in these folders.
+in small iterations. Don't create new docs in these folders.
 
 To move a document from its location to another directory, read the section
 [changing document location](doc_styleguide.md#changing-document-location) of the doc style guide.
@@ -116,6 +118,49 @@ 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, 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.
+
+- Use the current [merge request description template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/merge_request_templates/Documentation.md)
+- Use the correct [branch name](#branch-naming)
+- Label the MR `Documentation`
+- Assign the correct milestone (see note below)
+
+
+NOTE: **Note:**
+If the release version you want to add the documentation to has already been
+frozen or released, 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.
+
+Follow this [method for cherry-picking from CE to EE](automatic_ce_ee_merge.md#cherry-picking-from-ce-to-ee), with a few adjustments:
+
+- Create the [CE branch](#branch-naming) starting with `docs-`,
+  e.g.: `git checkout -b docs-example`
+- Create the EE-equivalent branch ending with `-ee`, e.g.,
+  `git checkout -b docs-example-ee`
+- Once all the jobs are passing in CE and EE, and you've addressed the
+feedback from your own team, assign the CE MR to a technical writer for review
+- When both MRs are ready, the EE merge request will be merged first, and the
+CE-equivalent will be merged next.
+- Note that the review will occur only in the CE MR, as the EE MR
+contains the same commits as the CE MR.
+- 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 though, 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