Merge branch 'docs-devguide-cherry-pick-ce-to-ee' into 'master'
Docs guidelines: cherry-picking commits from CE to EE Closes #41338 and #28822 See merge request gitlab-org/gitlab-ce!17367
This commit is contained in:
commit
2a97550d2f
|
@ -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)
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue