Plan for changes from 'auto_merge_labels_mr_widget' flag
What is happening
In %15.11, as part of gitlab#359057 (closed), the auto_merge_labels_mr_widget
feature flag is being rolled out. Initially disabled, this feature flag appears to affect two buttons in the UI. However, the problem is more complex and requires coordination:
- The wording on those two buttons (
merge train
andmerge when pipeline succeeds
) has been repurposed in multiple parts of the UI, overall user experience, and documentation. - The
merge train
feature belongs to devopsverify, and themerge when pipeline succeeds
feature belongs to devopscreate. The involved technical writers are @drcatherinepope (Verify) and @aqualls (Create). - The affected sets of documentation belong to two separate tiers (Create is free, Verify is not).
- The affected sets of documentation do not share a viable parent page that could contain the SSOT. Verify's docs are based in
doc/ci/
and Create's are based indoc/user/project/
. - Based on the discussion in gitlab!115436 (comment 1332073654), Kati and Catherine and I think it makes sense to intentionally break SSOT and have two sources of truth. One for
merge train
, one formerge when pipeline succeeds
.
I expect that after Catherine and I craft our SSOT announcements - one each for Verify and Create - we'll be working in parallel with little crossover. A single issue to use as 'related' for all of these items would probably help us understand, afterward, what it took to do this work.
devopsverify
Changes forHere, Amy looked for merge train
, and used a smaller subset of the bigger phrase because she knew a few variations existed.
Text changes
Easiest to fix. These text changes don't break inbound links to pages or subheadings.
doc/development/cicd/index.md
doc/development/code_review.md
doc/development/gitaly.md
doc/ci/troubleshooting.md
doc/ci/pipelines/merge_request_pipelines.md
doc/ci/pipelines/index.md
doc/ci/pipelines/cicd_minutes.md
doc/ci/yaml/workflow.md
doc/ci/yaml/index.md
doc/ci/jobs/job_control.md
doc/user/project/quick_actions.md
doc/user/todos.md
doc/api/api_resources.md // points to API renaming
doc/api/projects.md // API renaming
doc/api/graphql/reference/index.md // graphql renaming
doc/api/feature_flags.md
doc/api/feature_flags.md
doc/administration/audit_events.md
doc/administration/reference_architectures/2k_users.md
doc/administration/reference_architectures/10k_users.md
doc/administration/reference_architectures/25k_users.md
doc/administration/reference_architectures/3k_users.md
doc/administration/reference_architectures/5k_users.md
doc/administration/reference_architectures/50k_users.md
Link-breaking renames of subheadings and pages
Updating the wording on these pages affect either page names, subheadings, or both. As a result, inbound links will break. We should assume the link fixes will have ripple effects out to other projects, like www-gitlab-com
.
doc/ci/pipelines/merge_trains.md
doc/api/merge_trains.md
UI text changes
Amy hopes these are being handled by engineering in gitlab!115436 (merged) but hasn't checked.
gitlab.pot:msgid "Add to merge train"
gitlab.pot:msgid "Add to merge train when pipeline succeeds"
gitlab.pot:msgid "Merging immediately isn't recommended as it may negatively impact the existing merge train. Read the %{docsLinkStart}documentation%{docsLinkEnd} for more information."
gitlab.pot:msgid "Pipelines|merge train"
gitlab.pot:msgid "Pipeline|Merge train pipeline"
gitlab.pot:msgid "Pipeline|Merge train pipeline jobs can not be retried"
gitlab.pot:msgid "Pipeline|merge train"
gitlab.pot:msgid "ProjectSettings|Enable merge trains"
gitlab.pot:msgid "ProjectSettings|If merge trains are enabled, merging is only possible if the branch can be rebased without conflicts."
gitlab.pot:msgid "ProjectSettings|Merge requests approved for merge are queued, and pipelines validate the combined results of the source and target branches before merge. %{link_start}What are merge trains?%{link_end}"
gitlab.pot:msgid "ProjectSettings|What are merge trains?"
gitlab.pot:msgid "Start merge train"
gitlab.pot:msgid "Start merge train when pipeline succeeds"
gitlab.pot:msgid "Start merge train..."
gitlab.pot:msgid "Todos|Removed from Merge Train"
gitlab.pot:msgid "mrWidget|A merge train is a queued list of merge requests waiting to be merged into the target branch. The changes in each merge request are combined with the changes in earlier merge requests and tested before merge."
gitlab.pot:msgid "mrWidget|A new merge train has started and this merge request is the first of the queue."
gitlab.pot:msgid "mrWidget|Added to the merge train by %{merge_author}"
gitlab.pot:msgid "mrWidget|Added to the merge train. There are %{mergeTrainPosition} merge requests waiting to be merged"
gitlab.pot:msgid "mrWidget|Remove from merge train"
gitlab.pot:msgid "mrWidget|Set by %{merge_author} to be added to the merge train when the pipeline succeeds"
gitlab.pot:msgid "mrWidget|Set by %{merge_author} to start a merge train when the pipeline succeeds"
gitlab.pot:msgid "mrWidget|What is a merge train?"
devopscreate
Changes forAmy poked around looking for instances of two strings: MWPS
and pipeline succeeds
, and used a smaller subset of the bigger phrase because she knew a few variations existed.
Text changes
Easiest to fix. These text changes don't break inbound links to pages or subheadings.
Done already:
-
doc/development/code_review.md
-
doc/user/project/merge_requests/index.md
-
doc/api/rest/deprecations.md
Handling in GraphQL merge request gitlab!123095 (merged):
-
doc/api/graphql/reference/index.md
-
app/graphql/types/merge_request_type.rb
Unsure how to do yet:
-
doc/ci/troubleshooting.md
-
doc/ci/pipelines/merge_request_pipelines.md
-
doc/ci/jobs/job_control.md
-
doc/user/profile/notifications.md
// suggests we have UI strings -
doc/api/merge_requests.md
Link-breaking renames of subheadings and pages
Updating the wording on these pages affect either page names, subheadings, or both. As a result, inbound links will break. We should assume the link fixes will have ripple effects out to other projects, like www-gitlab-com
.
-
doc/ci/pipelines/merge_trains.md
-
doc/ci/pipelines/merge_request_pipelines.md
\ does this need a rename? I'm not sure -
doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
-
doc/api/merge_requests.md
-
doc/user/project/push_options.md
-
doc/user/project/merge_requests/widgets.md
UI text changes
Amy hopes these are being handled by engineering in gitlab!115436 (merged) but hasn't checked.
-
"Add to merge train when pipeline succeeds"
-
"Merge request was scheduled to merge after pipeline succeeds"
-
"Merge when pipeline succeeds"
-
"NotificationEvent|Merge when pipeline succeeds"
-
"Start merge train when pipeline succeeds"
-
"mrWidget|Set by %{merge_author} to be added to the merge train when the pipeline succeeds"
-
"mrWidget|Set by %{merge_author} to be merged automatically when the pipeline succeeds"
-
"mrWidget|Set by %{merge_author} to start a merge train when the pipeline succeeds"
-
"was scheduled to merge after pipeline succeeds by"
🎉 Surprises outside of the doc/
directory 🎉
Because of some work Amy did a year ago, she knew we had these phrases lurking in unusual areas outside of the documentation, but wasn't sure how widespread the problem was. What immediately came to her mind: MR/issue templates, email notifications, system notes, untranslated error messages. While these are probably best handled by engineering, they contain language changes. Catherine and Amy will want to keep an eye on them, and either review or contribute to the changes:
Other files that may need revision
Handled in gitlab!123092 (merged):
-
.gitlab/merge_request_templates/Removals.md
-
.gitlab/merge_request_templates/Deprecations.md
-
app/views/notify/merge_when_pipeline_succeeds_email.text.haml
-
app/views/notify/merge_when_pipeline_succeeds_email.html.haml
-
app/experiments/templates/new_project_readme_content/readme_advanced.md.tt
-
app/views/projects/readme_templates/default.md.tt
Not done or unsure:
-
app/services/system_notes/merge_requests_service.rb
-
ee/app/services/system_notes/merge_train_service.rb
-
ee/app/assets/javascripts/vue_merge_request_widget/components/merge_immediately_confirmation_dialog.vue
-
ee/app/services/merge_trains/create_pipeline_service.rb
(// return error('merge trains is disabled')
)
(Originally noted in gitlab!115436 (comment 1332088417).)
- Other repositories that might see effects:
-
www-gitlab-com
-
gitlab-vscode-extension
-
cli
cli!1285 (merged) -
pages
-
gitlab-docs
-
triage-ops
-
- Other oddities: the label Category:Merge Trains
Timeline
- %15.11: The feature flag MR (gitlab!115436 (merged)) should include the SSOT statements for Verify and Create, so both writers can get started.
- (Amy wonders if we're really going to change all the UI elements in the feature flag, or if we're going to hit just the major points and then clean up as part of %16.0)
- Determine: When should the docs update the wording? I (Amy) think we can leave it alone while it's enabled just on self-managed, but I think when we enable it on GitLab.com it's time to move.
- Determine: Change twice (to include both phrases for a period of time, while the enablement status is in flux) or change once and be done with it? Amy's a fan of change-once.
- Determine: Should the docs be updated in two passes: text-only, and link changes? The breadth of changes may make it tough to prep MRs in advance without them becoming full of conflicts. Also, the timing of when the enablement happens is important - in the last few days of the milestone (when things are often enabled) we can't always guarantee what changes will get in and which won't.