Merge branch 'smh-update-remote-mirror-behavior' into 'master'

Document the actual behavior of remote push mirroring

See merge request gitlab-org/gitlab!66555

app/views/projects/mirrors/_mirror_repos_push.html.haml

@@ -11,5 +11,5 @@
     = check_box_tag :keep_divergent_refs, '1', false, class: 'js-mirror-keep-divergent-refs form-check-input'
     = label_tag :keep_divergent_refs, _('Keep divergent refs'), class: 'form-check-label'
     .form-text.text-muted
-      = _('By default, if any ref (branch, tag, or commit) on the remote mirror has diverged from the local repository, the entire push will fail, and nothing will be updated. Choose this option to override this behavior. After the mirror is created, this can only be modified via the API.')
-      = link_to _('Learn more.'), help_page_path('user/project/repository/repository_mirroring', anchor: 'keep-divergent-refs'), target: '_blank', rel: 'noopener noreferrer'
+      - link_opening_tag = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe
+      = html_escape(_('Do not force push over diverged refs. After the mirror is created, this setting can only be modified using the API. %{mirroring_docs_link_start}Learn more about this option%{link_closing_tag} and %{mirroring_api_docs_link_start}the API.%{link_closing_tag}')) % { mirroring_docs_link_start: link_opening_tag % {url: help_page_path('user/project/repository/repository_mirroring', anchor: 'keep-divergent-refs')}, mirroring_api_docs_link_start: link_opening_tag % {url: help_page_path('api/remote_mirrors')}, link_closing_tag: '</a>'.html_safe }

doc/user/project/repository/repository_mirroring.md

@@ -92,19 +92,18 @@ You can also create and modify project push mirrors through the
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208828) in GitLab 13.0.
 
-By default, if any ref on the remote mirror has diverged from the local
-repository, the *entire push* fails, and no updates occur.
+By default, if any ref (branch or tag) on the remote mirror has diverged from the local repository, the local differences are forced to the remote.
 
-For example, if a repository has `main`, `develop`, and `stable` branches that
+For example, if a repository has `main` and `develop` branches that
 have been mirrored to a remote, and then a new commit is added to `develop` on
-the mirror, the next push attempt fails, leaving `main` and `stable`
-out-of-date despite not having diverged. No change on any branch can be mirrored
-until the divergence is resolved.
+the remote mirror. The next push updates all of the references on the remote mirror to match
+the local repository, and the new commit added to the remote `develop` branch is lost.
 
 With the **Keep divergent refs** option enabled, the `develop` branch is
-skipped, allowing `main` and `stable` to be updated. The mirror status
-reflects that `develop` has diverged and was skipped, and be marked as a failed
-update.
+skipped, causing only `main` to be updated. The mirror status
+reflects that `develop` has diverged and was skipped, and be marked as a
+failed update. Refs that exist in the mirror repository but not in the local
+repository are left untouched.
 
 NOTE:
 After the mirror is created, this option can only be modified via the [API](../../../api/remote_mirrors.md).

locale/gitlab.pot

@@ -5853,9 +5853,6 @@ msgstr ""
 msgid "By default, all projects and groups will use the global notifications setting."
 msgstr ""
 
-msgid "By default, if any ref (branch, tag, or commit) on the remote mirror has diverged from the local repository, the entire push will fail, and nothing will be updated. Choose this option to override this behavior. After the mirror is created, this can only be modified via the API."
-msgstr ""
-
 msgid "ByAuthor|by"
 msgstr ""
 
@@ -11720,6 +11717,9 @@ msgstr ""
 msgid "Do not display offers from third parties"
 msgstr ""
 
+msgid "Do not force push over diverged refs. After the mirror is created, this setting can only be modified using the API. %{mirroring_docs_link_start}Learn more about this option%{link_closing_tag} and %{mirroring_api_docs_link_start}the API.%{link_closing_tag}"
+msgstr ""
+
 msgid "Do you want to remove this deploy key?"
 msgstr ""