[DO NOT MERGE] Add user permission documentation and update owner references (#17787)

* update mentions of owners team to owner role

* update org overview

* remove callout and update org intro

* update owners team to owner role

* add company layer variable for edit roles

* update hub api doc

* fix typo

* update intro section and add subheadings

* add links to hub and admin for visibility

* move team permissions to org permissions table and update reference to repo permissions page

* cleanup

* update company owner role positioning

* add missing word

* cleanup table

* update section on team permissions

* update release notes and cleanup table

* implement feedback

* update for clarity

_data/glossary.yaml

@@ -197,8 +197,6 @@ overlay storage driver: |
   OverlayFS is a [filesystem](#filesystem) service for Linux which implements a
   [union mount](https://en.wikipedia.org/wiki/Union_mount) for other file systems.
   It is supported by the Docker daemon as a storage driver.
-owners team: |
-  The owners team is a special team created by default during the organization creation process. The owners team has full access to all repositories in the organization.
 parent image: |
   An image's **parent image** is the image designated in the `FROM` directive
   in the image's Dockerfile. All subsequent commands are based on this parent

_data/toc.yaml

@@ -2035,6 +2035,8 @@ manuals:
     title: Create and manage a team
   - path: /docker-hub/members/
     title: Manage members
+  - path: /docker-hub/roles-and-permissions/
+    title: Roles and permissions
   - sectiontitle: Single Sign-on
     section:
       -  path: /single-sign-on/

_includes/admin-image-access.md

@@ -30,7 +30,7 @@ You need to [configure a registry.json to enforce sign-in](/docker-hub/configure
 
     > **Note**
     >
-    > Image Access Management is turned off by default. However, members of the `owners` team in your organization have access to all images regardless of the settings.
+    > Image Access Management is turned off by default. However, owners in your organization have access to all images regardless of the settings.
 
 4. Select the category restrictions for your images by selecting **Allowed**.
      Once the restrictions are applied, your members can view the organization permissions page in a read-only format.

_includes/admin-org-overview.md

@@ -1,16 +1,14 @@
 An organization in Docker is a collection of teams and repositories
 that can be managed together. A team is a group of Docker members that belong to an organization.
-An organization can have multiple teams.
+An organization can have multiple teams. Members don't have to be added to a team to be part of an organization.
 
-Docker users become members of an organization
-when they are assigned to at least one team in the organization. When you first
-create an organization, you have one team, the "owners" team, that has a single member. An organization owner is someone that is part of the
-owners team. They can create new teams and add
-members to an existing team using their Docker ID or email address and by
-selecting a team the user should be part of. An organization owner can also add
+Docker users become members of an organization once they're associated with that organization by an organization owner. An organization owner is a user with administrative access to the organization.
+
+Owners can invite users, assign them roles, create new teams, and add
+members to an existing team using their Docker ID or email address. An organization owner can also add
 additional owners to help them manage users, teams, and repositories in the
 organization.
 
-The following diagram depicts the setup of an organization and how it relates to teams.
+The following diagram depicts the setup of an organization and how it relates to teams. Teams are an optional feature that owners can use to group members and assign permissions.
 
 ![organization-hierarchy](/admin/images/docker-hierarchy-org.svg){: width="700px" }

_includes/admin-users.md

@@ -6,9 +6,11 @@
   {% if include.layer == "company" %}
     {% assign member_navigation="Select your company in the left navigation drop-down menu, and then select **Users**." %}
     {% assign remove_button = "**Remove user**" %}
+    {% assign update_role = "Select their organization, select the role you want to assign, and then select **Save**." %}
   {% else %}
     {% assign member_navigation="Select your organization in the left navigation drop-down menu, and then select **Members**." %}
     {% assign remove_button = "**Remove member**" %}
+    {% assign update_role = "Select the role you want to assign, then select **Save**." %}
   {% endif %}
 {% else %}
   {% assign product_link="[Docker Hub](https://hub.docker.com)" %}
@@ -16,6 +18,7 @@
   {% assign invite_button = "**Invite members**" %}
   {% assign remove_button = "**Remove member**" %}
   {% assign export_button = "**Export members**" %}
+  {% assign update_role = "Select the role you want to assign, then select **Save**." %}
 {% endif %}
 
 ## Invite members
@@ -34,7 +37,7 @@ Use the following steps to invite members to your organization via Docker ID or
 
   > **Note**
   >
-  >  It is recommended that you invite non-administrative users to a team other than the owners team. Members in the owners team will have full access to your organization’s administrative settings.
+  >  When you invite members, you assign them a role. See [Roles and permissions](/docker-hub/roles-and-permissions/) for details about the access permissions for each role.
 
 Pending invitations appear in the table. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.
 
@@ -73,7 +76,7 @@ To invite multiple members to an organization via a CSV file containing email ad
 
   > **Note**
   >
-  >  It is recommended that you invite non-administrative users to a team other than the owners team. Members in the owners team will have full access to your organization’s administrative settings.
+  >  When you invite members, you assign them a role. See [Roles and permissions](/docker-hub/roles-and-permissions/) for details about the access permissions for each role.
 
 
 Pending invitations appear in the table. The invitees receive an email with a link to Docker Hub where they can accept or decline the invitation.
@@ -96,6 +99,22 @@ To remove a member from an organization:
 3. In the table, select the **Action** icon, and then select {{  remove_button  }} or **Remove invitee**.
 4. Follow the on-screen instructions to remove the member or invitee.
 
+## Update a member role
+
+Organization owners can manage [roles](/docker-hub/roles-and-permissions/) within an organization. If an organization is part of a company, the company owner can also manage that organization's roles.
+
+> **Note**
+>
+> If you're the only owner of an organization, you need to assign a new owner before you can edit your role.
+
+To update a member role:
+
+1. Sign in to {{ product_link }}{: target="_blank" rel="noopener" class="_"}.
+2. {{ member_navigation }}
+3. Find the username of the member whose role you want to edit. In the table, select the **Actions** icon.
+4. Select **Edit role**.
+5. {{ update_role }}
+
 ## Export members
 
 Owners can export a CSV file containing all members.

admin/index.md

@@ -12,8 +12,8 @@ The [Docker Admin](https://admin.docker.com){: target="_blank" rel="noopener" cl
 - Company: A company simplifies the management of Docker organizations and settings. Creating a company is optional and only available to Docker Business subscribers.
   - Company owner: A company can have multiple owners. Company owners have company-wide observability and can manage company-wide settings that apply to all associated organizations. In addition, company owners have the same access as organization owners for all associated organizations.
 - Organization: An organization is a collection of teams and repositories. Docker Team and Business subscribers must have at least one organization.
-  - Organization owner: An organization can have multiple owners that are members of the owners team. Organization owners have observability into their organization and can manage its users and settings.
-- Team: A team is a group of Docker members that belong to an organization. An organization has one team upon creation, the owners team. Organization and company owners can group members into additional teams to configure repository permissions on a per-team basis.
+  - Organization owner: An organization can have multiple owners. Organization owners have observability into their organization and can manage its users and settings.
+- Team: A team is a group of Docker members that belong to an organization. Organization and company owners can group members into additional teams to configure repository permissions on a per-team basis.
   - Member: A member is a Docker user that's a member of at least one team in an organization.
 
 <div class="component-container">

desktop/extensions/settings-feedback.md

@@ -17,7 +17,7 @@ Docker Extensions is switched on by default. To change your settings:
 
 >**Note**
 >
-> If you are an [organization owner](../../docker-hub/manage-a-team.md#the-owners-team), you can turn off extensions for your users. Navigate to the `settings.json` file, and set `"extensionsEnabled"` to `false`. 
+> If you are an [organization owner](../../docker-hub/manage-a-team.md#organization-owner), you can turn off extensions for your users. Navigate to the `settings.json` file, and set `"extensionsEnabled"` to `false`. 
 > The `settings.json` file is located at:
 >   - `~/Library/Group Containers/group.com.docker/settings.json` on Mac
 >   - `C:\Users\[USERNAME]\AppData\Roaming\Docker\settings.json` on Windows

docker-hub/api/latest.yaml

@@ -786,7 +786,7 @@ paths:
         Updates an organization's settings. Some settings are only used when the
         organization is on a business plan.
 
-        ***Only users in the "owners" group of the organization can use this endpoint.***
+        ***Only users with administrative privileges for the organization (owner role) can modify these settings.***
 
         The following settings are only used on a business plan:
         - `restricted_images`

docker-hub/builds/index.md

@@ -236,7 +236,7 @@ When you create an automated build repository in your own user account, you
 can start, cancel, and retry builds, and edit and delete your own repositories.
 
 These same actions are also available for team repositories from Docker Hub if
-you are a member of an organization's `Owners` team. If you are a member of a
+you are an owner. If you are a member of a
 team with `write` permissions you can start, cancel, and retry builds in your
 team's repositories, but you cannot edit the team repository settings or delete
 the team repositories. If your user account has `read` permission, or if you're
@@ -254,7 +254,7 @@ including any testing settings.
 
 > **Note**
 >
-> Only members of the `Owners` team can set up Automated builds for teams.
+> Only owners can set up Automated builds for teams.
 
 When you set up Automated builds for teams, you grant Docker Hub access to
 your source code repositories using OAuth tied to a specific user account. This
@@ -284,7 +284,7 @@ variable to automated builds associated with the account. For more information,
 
 4. Add the service user to the "build" team on the source provider.
 
-5. Sign in to Docker Hub as a member of the `Owners` team, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
+5. Sign in to Docker Hub as an owner, switch to the organization, and follow the instructions to [link to source code repository](link-source.md) using the service account.
 
     > **Note**
     >

docker-hub/convert-account.md

@@ -26,11 +26,11 @@ Before you convert a user account to an organization, ensure that you meet the f
     2. Find your username in the **Members** tab.
     3. Select the **More options** menu and then select **Leave organization**.
 
-    If the user account is the sole owner of any organization or company, add someone to the "owners" team and then remove yourself from the organization or company.
+    If the user account is the sole owner of any organization or company, assign another user the owner role and then remove yourself from the organization or company.
 
 -  You must have a separate Docker ID ready to assign it as the owner of the organization during conversion.
 
-    If you wish to convert your user account into an organization account and you do not have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. This user account then becomes the first member of the "owners" team and has full administrative access to configure and manage the organization. You can add more users into the "owners" team after the conversion.
+    If you wish to convert your user account into an organization account and you do not have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. With the owner role assigned, this user account has full administrative access to configure and manage the organization. You can assign more users the owner role after the conversion.
 
 ## Convert an account into an organization
 

docker-hub/deactivate-account.md

@@ -24,7 +24,7 @@ Before deactivating your Docker Hub account, ensure that you meet the following
     2. Find your username in the **Members** tab.
     3. Select the **More options** menu and then select **Leave organization**.
 
-- If you are the sole owner of an organization, either add someone to [the **owners** team](manage-a-team.md#the-owners-team) and then remove yourself from the organization, or deactivate the organization. Similarly, if you are the sole owner of a company, either add someone else as a company owner and then remove yourself, or deactivate the company.
+- If you are the sole owner of an organization, either assign another member of the organization the owner role and then remove yourself from the organization, or deactivate the organization. Similarly, if you are the sole owner of a company, either add someone else as a company owner and then remove yourself, or deactivate the company.
 
 - If you have an active subscription, [downgrade it to a Docker Personal subscription](../subscription/downgrade.md).
 
@@ -52,7 +52,7 @@ Before deactivating an organization, please complete the following:
 
 -  If you have an active subscription, [downgrade it to a **Docker Free Team** subscription](../subscription/downgrade.md).
 
-- Remove all other members, including those in the **Owners** team, within the organization.
+- Remove all other members within the organization.
 
 - Unlink your [Github and Bitbucket accounts](../docker-hub/builds/link-source.md#unlink-a-github-user-account).
 

docker-hub/general-faqs.md

@@ -22,10 +22,7 @@ class="_"} can retrieve the Docker ID for you.
 
 ### What’s an organization?
 
-Docker users become members of an organization when they are assigned to at
-least one team in the organization. When you first create an organization,
-you’ll see that you have a team, the **Owners** (Admins) team, with a single
-member. An organization owner is someone that is part of the owners team. They
+Docker users become members of an organization when they're associated with the organization by an organization owner. An organization owner is someone assigned the owner role. They
 can create new teams and add members to an existing team using their Docker ID
 or email address and by selecting a team the user should be part of. An
 organization owner can also add additional organization owners to help them
@@ -39,9 +36,13 @@ To begin, you should set up your first organization and contact the Customer Suc
 
 The organization name, sometimes referred to as the organization namespace or the org ID, is the unique identifier of a Docker organization. The organization name cannot be the same as an existing Docker ID.
 
+### What are roles?
+
+A role is a collection of permissions granted to members. Roles define access to perform actions in Docker Hub like creating repositories, managing tags, or viewing teams. See [Roles and permissions](roles-and-permissions.md).
+
 ### What’s a team?
 
-A **Team** is a group of Docker users that belong to an organization. An organization can have multiple teams. When you first create an organization, you’ll see that you have a team, the owners team, with a single member. An organization owner can then create new teams and add members to an existing team using Docker IDs or email address and by selecting a team the user should be part of. See [Create and manage a team](manage-a-team.md).
+A **Team** is a group of Docker users that belong to an organization. An organization can have multiple teams. An organization owner can then create new teams and add members to an existing team using Docker IDs or email address and by selecting a team the user should be part of. See [Create and manage a team](manage-a-team.md).
 
 ### What's a company?
 

docker-hub/manage-a-team.md

@@ -5,14 +5,12 @@ title: Create and manage a team
 ---
 
 A team is a group of Docker users that belong to an organization. An
-organization can have multiple teams. When you first create an organization,
-you’ll see that you have a team (called 'Company') and the owners team, with a single member. An
+organization can have multiple teams. An
 organization owner can then create new teams and add members to an existing team
-using their Docker ID or email address and by selecting a team the user should be part of.
+using their Docker ID or email address and by selecting a team the user should be part of. Members aren't required to be part of a team to be associated with an organization.
 
-The org owner can add additional org owners to the owners team to help them
-manage users, teams, and repositories in the organization. See [Owners
-team](#the-owners-team) for details.
+The organization owner can add additional organization owners to help them
+manage users, teams, and repositories in the organization by assigning them the owner role.
 
 ## Create a team
 
@@ -21,10 +19,7 @@ team](#the-owners-team) for details.
 3. Fill out your team's information and select **Create**.
 4. [Add members to your team](members.md#add-a-member-to-a-team)
 
-## The owners team
-
-The owners team is a special team created by default during the org creation
-process. The owners team has full access to all repositories in the organization.
+## Organization owner
 
 An organization owner is an administrator who is responsible to manage
 repositories and add team members to the organization. They have full access to
@@ -57,6 +52,8 @@ To give a team access to a repository
 
     ![Team Repo Permissions](images/team-repo-permission.png){:width="700px"}
 
+Organization owners can also assign members the editor role to grant partial administrative access. See [Roles and permissions](/docker-hub/roles-and-permissions/) for more about the editor role.
+
 ### Permissions reference
 
 - `Read-only` access lets users view, search, and pull a private repository in the same way as they can a public repository.

docker-hub/onboard-business.md

@@ -33,7 +33,7 @@ To begin, you should identify which users you will need to add to your Docker Bu
 
 Now that you have a Docker Business organization, it's time to start adding owners to help you set up and manage your organization. Owners can add or remove members, and configure Single Sign-on as well as other security settings.
 
-To add an owner, invite a user to the **owners** team. For more details, see [Invite members](../docker-hub/members.md/#invite-members){: target="_blank" rel="noopener" class="_"}.
+To add an owner, invite a user and assign them the owner role. For more details, see [Invite members](../docker-hub/members.md/#invite-members){: target="_blank" rel="noopener" class="_"}.
 
 ## Step 3: Invite members
 

docker-hub/onboard-team.md

@@ -33,7 +33,7 @@ To begin, you should identify which users you will need to add to your Docker Te
 
 Now that you have a Docker Team organization, it's time to start adding owners to help you set up and manage your organization. Owners can add or remove members, and configure other organization settings.
 
-To add an owner, invite a user to the **owners** team. For more details, see [Invite members](../docker-hub/members.md/#invite-members){: target="_blank" rel="noopener" class="_"}.
+To add an owner, invite a user and assign them the owner role. For more details, see [Invite members](../docker-hub/members.md/#invite-members){: target="_blank" rel="noopener" class="_"}.
 
 ## Step 3: Invite members
 

docker-hub/organization-faqs.md

@@ -18,7 +18,7 @@ An existing owner can add additional team members as organization owners. All
 they need to do is select the organization from the
 [Organizations](https://hub.docker.com/orgs){: target="_blank" rel="noopener"
 class="_"} page in Docker Hub, add the Docker ID/Email of the user, and then
-select the **Owners** team from the drop-down menu. See [The owners team](manage-a-team.md#the-owners-team).
+select the owner role from the drop-down menu. See [Organization owner](manage-a-team.md#organization-owner).
 
 ### Do users first need to authenticate with Docker before an owner can add them to an organization?
 

docker-hub/orgs.md

@@ -56,7 +56,7 @@ you require.
    > Instead, select **Organizations** to verify that the organization has been
    > created.
 
-You've now created an organization with one team, the owners team, with you as the single member.
+You've now created an organization.
 
 ## View an organization
 
@@ -102,7 +102,7 @@ configure your organization.
   organization, and allows you to view and change your repository privacy
   settings, configure org permissions such as
   [Image Access Management](image-access-management.md), configure notification settings, and [deactivate](deactivate-account.md#deactivate-an-organization) your
-  organization. You can also update your organization name and company name that appear on your organization landing page. You must be part of the owners team to access the
+  organization. You can also update your organization name and company name that appear on your organization landing page. You must be an owner to access the
    organization's **Settings** page.
 
 - **Billing**: Displays information about your existing

docker-hub/release-notes.md

@@ -11,6 +11,12 @@ known issues for each Docker Hub release.
 
 Take a look at the [Docker Public Roadmap](https://github.com/docker/roadmap/projects/1){: target="_blank" rel="noopener" class="_"} to see what's coming next.
 
+## 2023-07-26
+
+### New
+
+- Organizations can assign the [editor role](roles-and-permissions.md) to members to grant additional permissions without full administrative access.
+
 ## 2023-05-09
 
 ### New

docker-hub/repos/create.md

@@ -22,7 +22,7 @@ command.
 When creating a new repository:
 
 - You can choose to locate it under your own user account, or under any
-  [organization](../../docker-hub/orgs.md) where you are an [owner](../manage-a-team.md#the-owners-team).
+  [organization](../../docker-hub/orgs.md) where you are an [owner](../manage-a-team.md#organization-owner).
 - The repository name needs to:
     - Be unique 
     - Have between 2 and 255 characters

docker-hub/roles-and-permissions.md

@@ -0,0 +1,78 @@
+---
+description: Use roles in your organization to control who has access to content, registry, and organization management permissions.
+keywords: members, teams, organization, company, roles, access
+title: Roles and permissions
+---
+
+Organization and company owners can assign roles to individuals giving them different permissions in the organization. This section is for owners who want to learn about the defined roles and their permission scopes.
+
+## Roles
+
+When you invite users to your organization, you assign a role. A role is a collection of permissions. Roles define access to perform actions like creating repositories, pulling images, creating teams, and configuring organization settings.
+
+The following roles are available to assign:
+
+- **Member** - Non-administrative role. Members can view other members that are in the same organization.
+- **Editor** - Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions.
+- **Organization owner** - Full organization administrative access. Organization owners can manage organization repositories, teams, members, settings, and billing.
+- **Company owner** - In addition to the permissions of an organization owner, company owners can configure settings for their associated organizations.
+
+Owners can manage roles for members of an organization on [Docker Hub](/docker-hub/members/#update-a-member-role), as well members of an [organization](/admin/organization/members/#update-a-member-role) or a [company](/admin/company/users/#update-a-member-role) on [Docker Admin](/admin/).
+
+## Permissions
+
+The following sections describe the permissions for each role.
+
+### Content and registry permissions
+
+The following outlines content and registry permissions for member, editor, and organization owner roles. These permissions and roles apply to the entire organization, including all the repositories in the namespace for the organization.
+
+Company owners have the same access as organization owners for all associated organizations. See [Company overview](/admin/company/).
+
+| Permission | Member | Editor | Organization owner |
+|:----------------------- |:------ |:-------|:------------------ |
+| Explore images and extensions | ✅ | ✅ | ✅ |
+| Star, favorite, vote, and comment on content | ✅ | ✅ | ✅ |
+| Pull images | ✅ | ✅ | ✅ |
+| Create and publish an extension | ✅ | ✅ | ✅ |
+| Become a Verified, Official, or Open Source publisher | ❌ | ❌ | ✅ |
+| Observe content engagement as a publisher | ❌ | ❌ | ✅ |
+| Create public and private repositories | ❌ | ✅ | ✅ |
+| Edit and delete repositories | ❌ | ✅ | ✅ |
+| Manage tags | ❌ | ✅ | ✅ |
+| View repository activity | ❌ | ❌ | ✅ |
+| Set up Automated builds | ❌ | ❌ | ✅ |
+| Edit build settings | ❌ | ❌ | ✅ |
+| Set up vulnerability analysis with Docker Scout | ❌ | ✅ | ✅ |
+| View teams | ❌ | ✅ | ✅ |
+| Assign team permissions to repositories | ❌ | ✅ | ✅ |
+
+When you add members to a team, you can manage their repository permissions. For team repository permissions, see [Create and manage a team permissions reference](/docker-hub/manage-a-team/#permissions-reference).
+
+### Organization management permissions
+
+The following outlines organization management permissions for member, editor, organization owner, and company owner roles.
+
+| Permission | Member | Editor | Organization owner | Company owner |
+|:----------------------- |:------ |:-------|:------------------ |:----------- |
+| Create teams | ❌ | ❌ | ✅ | ✅ |
+| Manage teams (including delete) | ❌ | ❌ | ✅ | ✅ |
+| Configure the organization's settings (including linked services) | ❌ | ❌ | ✅ | ✅ |
+| Add organizations to a company | ❌ | ❌ | ✅ | ✅ |
+| Invite members | ❌ | ❌ | ✅ | ✅ |
+| Manage members | ❌ | ❌ | ✅ | ✅ |
+| Manage member roles and permissions | ❌ | ❌ | ✅ | ✅ |
+| View member activity | ❌ | ❌ | ✅ | ✅ |
+| Export and reporting | ❌ | ❌ | ✅ | ✅ |
+| Image Access Management | ❌ | ❌ | ✅ | ✅ |
+| Registry Access Management | ❌ | ❌ | ✅ | ✅ |
+| Set up Single Sign-On (SSO) and SCIM | ❌ | ❌ | ✅ * | ✅ |
+| Require Desktop login | ❌ | ❌ | ✅ * | ✅ |
+| Manage billing information (e.g. billing address) | ❌ | ❌ | ✅ | ✅ |
+| Manage payment methods (e.g. credit card or invoice) | ❌ | ❌ | ✅ | ✅ |
+| View billing history | ❌ | ❌ | ✅ | ✅ |
+| Manage subscriptions | ❌ | ❌ | ✅ | ✅ |
+| Manage seats | ❌ | ❌ | ✅ | ✅ |
+| Upgrade and downgrade plans | ❌ | ❌ | ✅ | ✅ |
+
+_* If not part of a company_

docker-hub/slack_integration.md

@@ -16,7 +16,7 @@ Before you begin, make sure that you are signed into the Slack team that you wan
 
 1. Log in to the Docker account that owns the builds that you want to receive notifications about.
 
-    > **Note**: If you are setting up notifications for an organization, log in as a member of the organization's `Owners` team, then switch to the organization account to change the settings.
+    > **Note**: If you are setting up notifications for an organization, log in as an organization owner, then switch to the organization account to change the settings.
 
 2. Click **Account Settings** in the left hand navigation, and scroll down to the **Notifications** section.