diff options
Diffstat (limited to 'doc/development/documentation/index.md')
| -rw-r--r-- | doc/development/documentation/index.md | 62 |
1 files changed, 61 insertions, 1 deletions
diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 52a4bb27817..c7fa40af930 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -52,6 +52,62 @@ Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is See the [Structure](styleguide.md#structure) section of the [Documentation Style Guide](styleguide.md). +## Single codebase + +We currently maintain two sets of docs: one in the +[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). +They are similar, and most pages are identical, but they are different repositories. +With the single codebase effort, we want to make those two sets identical, so when the +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 + +After a given documentation path is aligned across CE and EE, all merge requests +affecting that path must be submitted to CE, regardless of the content it has. +This means that: + +* For **EE-only docs changes**, you only have to submit a CE MR. +* 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 +and without a changelog entry. + +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 +[product badges](styleguide.md#product-badges) for all EE documentation, so that +we can discern which features belong to which tier. + +### EE specific lines check + +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)), +which, among others, checks and prevents creating/editing new files and directories +in EE under `doc/`. + +We have a long list of documentation paths that are either whitelisted or not. +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 a document's location requires specific steps to be followed to ensure that @@ -415,7 +471,7 @@ If you want to know the in-depth details, here's what's really happening: The following GitLab features are used among others: - [Manual actions](../../ci/yaml/README.md#whenmanual) -- [Multi project pipelines](https://docs.gitlab.com/ee/ci/multi_project_pipeline_graphs.html) +- [Multi project pipelines](../../ci/multi_project_pipeline_graphs.md) - [Review Apps](../../ci/review_apps/index.md) - [Artifacts](../../ci/yaml/README.md#artifacts) - [Specific Runner](../../ci/runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) @@ -438,6 +494,10 @@ Currently, the following tests are in place: As CE is merged into EE once a day, it's important to avoid merge conflicts. Submitting an EE-equivalent merge request cherry-picking all commits from CE to EE is essential to avoid them. +1. [`ee-files-location-check`/`ee-specific-lines-check`](#ee-specific-lines-check) (runs on EE only): + This test ensures that no new files/directories are created/changed in EE. + All docs should be submitted in CE instead, regardless the tier they are on. + This is for the [single codebase](#single-codebase) effort. 1. In a full pipeline, tests for [`/help`](#gitlab-help-tests). ### Linting |