Add latest changes from gitlab-org/gitlab@master

1 files changed, 60 insertions, 35 deletions

diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 196f2afcfe3..2bf7f24bbab 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -241,58 +241,83 @@ nested groups if you have membership in one of its parents.
 To learn more, read through the documentation on
 [subgroups memberships](group/subgroups/index.md#membership).
 
-## Free Guest users **(ULTIMATE)**
-
-When a user is given `Guest` permissions on a project and/or group, and holds no
-higher permission level on any other project or group on the instance, the user
-is considered a guest user by GitLab and will not consume a license seat.
-There is no other specific "guest" designation for newly created users.
-
-If the user is assigned a higher role on any projects or groups, the user will
-take a license seat. If a user creates a project, the user becomes a `Maintainer`
-on the project, resulting in the use of a license seat.
-
-To prevent a guest user from creating projects, you can edit the user profile to mark the user as
-[External](#external-users-permissions).
-
-## External users permissions
+## External users **(CORE ONLY)**
 
 In cases where it is desired that a user has access only to some internal or
 private projects, there is the option of creating **External Users**. This
 feature may be useful when for example a contractor is working on a given
 project and should only have access to that project.
 
-External users can only access projects to which they are explicitly granted
-access, thus hiding all other internal or private ones from them. Access can be
-granted by adding the user as member to the project or group.
+External users:
+
+- Cannot create groups or projects.
+- Can only access projects to which they are explicitly granted access,
+  thus hiding all other internal or private ones from them (like being
+  logged out).
 
+Access can be granted by adding the user as member to the project or group.
 They will, like usual users, receive a role in the project or group with all
-the abilities that are mentioned in the table above. They cannot however create
-groups or projects, and they have the same access as logged out users in all
-other cases.
+the abilities that are mentioned in the [permissions table above](#project-members-permissions).
+For example, if an external user is added as Guest, and your project is
+private, they will not have access to the code; you would need to grant the external
+user access at the Reporter level or above if you want them to have access to the code. You should
+always take into account the
+[project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions)
+as well as the permission level of the user.
 
-An administrator can flag a user as external [through the API](../api/users.md)
-or by checking the checkbox on the admin panel. As an administrator, navigate
-to **Admin > Users** to create a new user or edit an existing one. There, you
-will find the option to flag the user as external.
+NOTE: **Note:**
+External users still count towards a license seat.
+
+An administrator can flag a user as external by either of the following methods:
 
-By default new users are not set as external users. This behavior can be changed
-by an administrator under **Admin > Application Settings**.
+- Either [through the API](../api/users.md#user-modification).
+- Or by navigating to the **Admin area > Overview > Users** to create a new user
+  or edit an existing one. There, you will find the option to flag the user as
+  external.
 
-### Default internal users
+### Setting new users to external
 
-The "Internal users" field allows specifying an e-mail address regex pattern to identify default internal users.
+By default, new users are not set as external users. This behavior can be changed
+by an administrator under the **Admin Area > Settings > General > Account and limit** page.
 
-New users whose email address matches the regex pattern will be set to internal by default rather than an external collaborator.
+If you change the default behavior of creating new users as external, you will
+have the option to narrow it down by defining a set of internal users.
+The **Internal users** field allows specifying an email address regex pattern to
+identify default internal users. New users whose email address matches the regex
+pattern will be set to internal by default rather than an external collaborator.
 
-The regex pattern format is Ruby, but it needs to be convertible to JavaScript, and the ignore case flag will be set, e.g. "/regex pattern/i".
+The regex pattern format is Ruby, but it needs to be convertible to JavaScript,
+and the ignore case flag will be set (`/regex pattern/i`). Here are some examples:
 
-Here are some examples:
+- Use `\.internal@domain\.com$` to mark email addresses ending with
+  `.internal@domain.com` as internal.
+- Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses
+  NOT including `.ext@domain.com` as internal.
 
-- Use `\.internal@domain\.com$` to mark email addresses ending with ".internal@domain.com" internal.
-- Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses NOT including .ext@domain.com internal.
+CAUTION: **Warning:**
+Be aware that this regex could lead to a
+[regular expression denial of service (ReDoS) attack](https://en.wikipedia.org/wiki/ReDoS).
+
+## Free Guest users **(ULTIMATE)**
 
-Please be aware that this regex could lead to a DOS attack, [see](https://en.wikipedia.org/wiki/ReDoS?) ReDos on Wikipedia.
+When a user is given Guest permissions on a project, group, or both, and holds no
+higher permission level on any other project or group on the GitLab instance,
+the user is considered a guest user by GitLab and will not consume a license seat.
+There is no other specific "guest" designation for newly created users.
+
+If the user is assigned a higher role on any projects or groups, the user will
+take a license seat. If a user creates a project, the user becomes a Maintainer
+on the project, resulting in the use of a license seat. Also, note that if your
+project is internal or private, Guest users will have all the abilities that are
+mentioned in the [permissions table above](#project-members-permissions) (they
+will not be able to browse the project's repository for example).
+
+TIP: **Tip:**
+To prevent a guest user from creating projects, as an admin, you can edit the
+user's profile to mark the user as [external](#external-users-core-only).
+Beware though that even if a user is external, if they already have Reporter or
+higher permissions in any project or group, they will **not** be counted as a
+free guest user.
 
 ## Auditor users **(PREMIUM ONLY)**