Merge branch 'mk-clarify-moving-namespaces' into 'master'

app/views/profiles/accounts/show.html.haml

@@ -74,7 +74,9 @@
       %h4.prepend-top-0.warning-title
         Change username
       %p
-        Changing your username will change path to all personal projects!
+        Changing your username can have unintended side effects.
+        = succeed '.' do
+          = link_to 'Learn more', help_page_path('user/profile/index', anchor: 'changing-your-username'), target: '_blank'
     .col-lg-8
       = form_for @user, url: update_username_profile_path, method: :put, html: {class: "update-username"} do |f|
         .form-group

app/views/shared/_group_form.html.haml

@@ -22,11 +22,9 @@
 
     - if @group.persisted?
       .alert.alert-warning.prepend-top-10
-        %ul
-          %li Changing group path can have unintended side effects.
-          %li Renaming group path will rename directory for all related projects
-          %li It will change web url for access group and group projects.
-          %li It will change the git path to repositories under this group.
+        Changing group path can have unintended side effects.
+        = succeed '.' do
+          = link_to 'Learn more', help_page_path('user/group/index', anchor: 'changing-a-groups-path'), target: '_blank'
 
 .form-group.group-name-holder
   = f.label :name, class: 'control-label' do

changelogs/unreleased/mk-clarify-moving-namespaces.yml

+---
+title: Expand docs for changing username or group path
+merge_request: 13914
+author:
+type: other

doc/user/group/index.md

@@ -188,6 +188,27 @@ Besides giving you the option to edit any settings you've previously
 set when [creating the group](#create-a-new-group), you can also
 access further configurations for your group.
 
+#### Changing a group's path
+
+> **Note:** If you want to retain ownership over the original namespace and
+protect the URL redirects, then instead of changing a group's path or renaming a
+username, you can create a new group and transfer projects to it.
+
+Changing a group's path can have unintended side effects.
+
+* Existing web URLs for the group and anything under it (i.e. projects) will
+redirect to the new URLs
+* Existing Git remote URLs for projects under the group will no longer work, but
+Git responses will show an error with the new remote URL
+* The original namespace can be claimed again by any group or user, which will
+destroy web redirects and Git remote warnings
+* If you are vacating the path so it can be claimed by another group or user,
+you may need to rename the group name as well since both names and paths must be
+unique
+
+> It is currently not possible to rename a namespace if it contains a
+project with container registry tags, because the project cannot be moved.
+
 #### Enforce 2FA to group members
 
 Add a security layer to your group by

doc/user/profile/index.md

@@ -8,10 +8,27 @@ experience according to the best approach to their cases.
 Your `username` is a unique [`namespace`](../group/index.md#namespaces)
 related to your user ID.
 
+### Changing your username
+
 You can change your `username` from your
-[profile settings](#profile-settings). To avoid breaking
-paths when you change your `username`, we suggest you follow
-[this procedure from the GitLab Team Handbook](https://about.gitlab.com/handbook/tools-and-tips/#how-to-change-your-username-at-gitlabcom).
+[profile settings](#profile-settings).
+
+> **Note:** If you want to retain ownership over the original namespace and
+protect the URL redirects, then instead of changing your username, you can
+create a new group and transfer projects to it.
+Alternatively, you can follow [this detailed procedure from the GitLab Team Handbook](https://about.gitlab.com/handbook/tools-and-tips/#how-to-change-your-username-at-gitlabcom).
+
+Changing your username can have unintended side effects.
+
+* Existing web URLs for the user and anything under it (i.e. projects) will
+redirect to the new URLs
+* Existing Git remote URLs for projects under the user will no longer work, but
+Git responses will show an error with the new remote URL
+* The original namespace can be claimed again by any group or user, which will
+destroy any web redirects and Git remote warnings
+
+> It is currently not possible to rename a namespace if it contains a
+project with container registry tags, because the project cannot be moved.
 
 ## User profile