Update guidance for EE doc submissions

This commit is contained in:
Marcel Amirault 2019-07-25 14:26:38 +00:00 committed by Marcia Ramos
parent 3e5d3998c9
commit ac7746de01

View file

@ -57,35 +57,22 @@ See the [Structure](styleguide.md#structure) section of the [Documentation Style
We currently maintain two sets of docs: one in the We currently maintain two sets of docs: one in the
[gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) repo and [gitlab-ce](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc) repo and
one in [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc). one in [gitlab-ee](https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc).
They are similar, and most pages are identical, but they are different repositories. They are identical, but they are different repositories. When the
With the single codebase effort, we want to make those two sets identical, so when the time comes to have only one codebase for the GitLab project, we'll be ready.
time comes to have only one codebase, we'll be ready.
Here are some links to get you up to speed with the current effort:
- [CE/EE codebases blueprint](https://about.gitlab.com/handbook/engineering/infrastructure/blueprint/ce-ee-codebases/)
- [CE/EE codebases merge design](https://about.gitlab.com/handbook/engineering/infrastructure/design/merge-ce-ee-codebases/)
- [Single docs codebase epic](https://gitlab.com/groups/gitlab-org/-/epics/199)
- [Issue board of related issues](https://gitlab.com/groups/gitlab-org/-/boards/981090?&label_name[]=Documentation&label_name[]=single%20codebase)
- [Related merge requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=all&label_name[]=Documentation&label_name[]=single%20codebase)
- [Visualize the existing diffs](https://leipert-projects.gitlab.io/is-gitlab-pretty-yet/diff/?search=%5Edoc)
### CE first ### CE first
After a given documentation path is aligned across CE and EE, all merge requests All merge requests for documentation must be submitted to CE, regardless of the content
affecting that path must be submitted to CE, regardless of the content it has. it has. This means that:
This means that:
- For **EE-only docs changes**, you only have to submit a CE MR. - For **EE-only docs changes**, you only have to submit an MR in the CE project.
- For **EE-only features** that touch both the code and the docs, you have to submit - For **EE-only features** that touch both the code and the docs, you have to submit
an EE MR containing all changes, and a CE MR containing only the docs changes an EE MR containing all code changes, and a CE MR containing only the docs changes
and without a changelog entry. and without a changelog entry.
This might seem like a duplicate effort, but it's only for the short term. This might seem like a duplicate effort, but it's only for the short term.
A list of the already aligned docs can be found in
[the epic description](https://gitlab.com/groups/gitlab-org/-/epics/199#ee-specific-lines-check).
Since the docs will be combined, it's crucial to add the relevant Since the CE and EE docs are combined, it's crucial to add the relevant
[product badges](styleguide.md#product-badges) for all EE documentation, so that [product badges](styleguide.md#product-badges) for all EE documentation, so that
we can discern which features belong to which tier. we can discern which features belong to which tier.
@ -94,19 +81,9 @@ we can discern which features belong to which tier.
There's a special test in place There's a special test in place
([`ee_specific_check.rb`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/ee_specific_check/ee_specific_check.rb)), ([`ee_specific_check.rb`](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/scripts/ee_specific_check/ee_specific_check.rb)),
which, among others, checks and prevents creating/editing new files and directories which, among others, checks and prevents creating/editing new files and directories
in EE under `doc/`. in EE under `doc/`. This should fail when changes to anything in `/doc` are submitted
in an EE MR. To pass the test, simply remove the docs changes from the EE MR, and
We have a long list of documentation paths that are either whitelisted or not. [submit them in CE](#ce-first).
Paths in the whitelist (not commented out) will not be subject to the test,
which means you are allowed to create/change docs content in EE for the time
being. The goal is to not have any doc whitelisted.
At the time of this writing, the only items left to be aligned are the API docs:
- `doc/api/*` ([issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/60045) / [merge request](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27491))
Eventually, once all docs are aligned, we'll remove any doc reference from that
script, so it catches everything.
## Changing document location ## Changing document location