[Nov 10 2021] Team notifications (github#22252)

* Describe new "only notify requested members" changes

* Rename file

* Update links

* Update gated feature callout

* Restructure a bit

* Use feature flag

* Rearrange conditional

* Fix procedural versioning

* Restructure again

* Remove screenshot

* Fix versioning

* Split out version for recent other enhancements

* This will be shipped in GHES 3.4 not 3.5

* Close liquid tag

* Remove incorrect table row

Co-authored-by: Laura Coursen <[email protected]>
Co-authored-by: Melanie Yarbrough <[email protected]>
Co-authored-by: Ethan Palm <[email protected]>

content/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile.md

@@ -109,7 +109,7 @@ When you set your status, you can also let people know that you have limited ava
 
 ![Requested reviewer shows "busy" note next to username](/assets/images/help/profile/request-a-review-limited-availability-status.png)
 
-If you select the "Busy" option, when people @mention your username, assign you an issue or pull request, or request a pull request review from you, a note next to your username will show that you're busy. You will also be excluded from automatic review assignment for pull requests assigned to any teams you belong to. For more information, see "[Managing code review assignment for your team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team)."
+If you select the "Busy" option, when people @mention your username, assign you an issue or pull request, or request a pull request review from you, a note next to your username will show that you're busy. You will also be excluded from automatic review assignment for pull requests assigned to any teams you belong to. For more information, see "[Managing code review settings for your team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)."
 
 1. In the top right corner of {% ifversion fpt or ghec %}{% data variables.product.prodname_dotcom_the_website %}{% else %}{% data variables.product.product_name %}{% endif %}, click your profile photo, then click **Set your status** or, if you already have a status set, click your current status.
   ![Button on profile to set your status](/assets/images/help/profile/set-status-on-profile.png)

content/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization.md

@@ -185,7 +185,7 @@ Some of the features listed below are limited to organizations using {% data var
 | Reinstate former members to the organization | **X** | | |
 | Add and remove people from **all teams** | **X** |  |  
 | Promote organization members to *team maintainer* | **X** |  |
-| Configure code review assignments (see "[Managing code review assignment for your team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team)") | **X** |  |
+| Configure code review assignments (see "[Managing code review settings for your team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)")) | **X** |  |
 | Add collaborators to **all repositories** | **X** |  |
 | Access the organization audit log | **X** |  |
 | Edit the organization's profile page (see "[About your organization's profile](/github/setting-up-and-managing-your-github-profile/customizing-your-profile/about-your-organizations-profile)" for details) | **X** |  |  |{% ifversion ghes > 3.1 %}

content/organizations/organizing-members-into-teams/index.md

@@ -26,7 +26,7 @@ children:
   - /adding-organization-members-to-a-team
   - /assigning-the-team-maintainer-role-to-a-team-member
   - /setting-your-teams-profile-picture
-  - /managing-code-review-assignment-for-your-team
+  - /managing-code-review-settings-for-your-team
   - /renaming-a-team
   - /changing-team-visibility
   - /synchronizing-a-team-with-an-identity-provider-group

content/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team.md → content/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team.md

@@ -1,8 +1,9 @@
 ---
-title: Managing code review assignment for your team
-intro: Code review assignments clearly indicate which members of a team are expected to submit a review for a pull request.
+title: Managing code review settings for your team
+intro: You can decrease noise for your team by limiting notifications when your team is requested to review a pull request.
 redirect_from:
   - /github/setting-up-and-managing-organizations-and-teams/managing-code-review-assignment-for-your-team
+  - /organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team
 product: '{% data reusables.gated-features.code-review-assignment %}'
 versions:
   fpt: '*'
@@ -12,21 +13,34 @@ versions:
 topics:
   - Organizations
   - Teams
-shortTitle: Code review assignment
-permissions: Team maintainers and organization owners can configure code review assignments.
+shortTitle: Code review settings
+permissions: Team maintainers and organization owners can configure code review settings.
 ---
 
-## About code review assignments
+## About code review settings
 
-By using code review assignments, any time your team has been requested to review a pull request, the team is removed as a reviewer and a specified subset of team members are assigned in the team's place. Code review assignments allow you to decide whether the whole team or just a subset of team members are notified when a team is requested for review.
+{% if only-notify-requested-members %}
+To reduce noise for your team and clarify individual responsibility for pull request reviews, you can configure code review settings.
+
+- Team notifications
+- Auto assignment
+
+## About team notifications
+
+When you choose to only notify requested team members, you disable sending notifications to the entire team when the team is requested to review a pull request if a specific member of that team is also requested for review. This is especially useful when a repository is configured with teams as code owners, but contributors to the repository often know a specific individual that would be the correct reviewer for their pull request. For more information, see "[About code owners](/github/creating-cloning-and-archiving-repositories/about-code-owners)."
+
+## About auto assignment
+{% endif %}
+
+When you enable auto assignment, any time your team has been requested to review a pull request, the team is removed as a reviewer and a specified subset of team members are assigned in the team's place. Code review assignments allow you to decide whether the whole team or just a subset of team members are notified when a team is requested for review.
 
 When code owners are automatically requested for review, the team is still removed and replaced with individuals. The individual approvals don't satisfy the requirement for code owner approval in a protected branch. For more information, see "[About code owners](/github/creating-cloning-and-archiving-repositories/about-code-owners)."
 
 {% ifversion fpt %}
 To further enhance your team's collaboration abilities, you can upgrade to {% data variables.product.prodname_ghe_cloud %}, which includes features like protected branches and code owners on private repositories. {% data reusables.enterprise.link-to-ghec-trial %}
 {% endif %}
 
-## Routing algorithms
+### Routing algorithms
 
 Code review assignments automatically choose and assign reviewers based on one of two possible algorithms. 
 
@@ -36,29 +50,45 @@ The load balance algorithm chooses reviewers based on each member's total number
 
 Any team members that have set their status to "Busy" will not be selected for review. If all team members are busy, the pull request will remain assigned to the team itself. For more information about user statuses, see "[Setting a status](/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/personalizing-your-profile#setting-a-status)."
 
-## Configuring code review assignment
+{% if only-notify-requested-members %}
+## Configuring team notifications
+
+{% data reusables.profile.access_org %}
+{% data reusables.user_settings.access_org %}
+{% data reusables.organizations.specific_team %}
+{% data reusables.organizations.team_settings %}
+5. In the left sidebar, click **Code review**
+![Code review button](/assets/images/help/teams/review-button.png)
+2. Select **Only notify requested team members.**
+![Code review team notifications](/assets/images/help/teams/review-assignment-notifications.png)
+3. Click **Save changes**.
+{% endif %}
+
+## Configuring auto assignment
 {% data reusables.profile.access_org %}
 {% data reusables.user_settings.access_org %}
 {% data reusables.organizations.specific_team %}
 {% data reusables.organizations.team_settings %}
-5. In the left sidebar, click **Code review assignment**
-![Code review assignment button](/assets/images/help/teams/review-assignment-button.png)
+5. In the left sidebar, click **Code review**
+![Code review button](/assets/images/help/teams/review-button.png)
 6. Select **Enable auto assignment**.
-![Code review assignment button](/assets/images/help/teams/review-assignment-enable.png)
+![Auto-assignment button](/assets/images/help/teams/review-assignment-enable.png)
 7. Under "How many team members should be assigned to review?", use the drop-down menu and choose a number of reviewers to be assigned to each pull request.
 ![Number of reviewers dropdown](/assets/images/help/teams/review-assignment-number.png)
 8. Under "Routing algorithm", use the drop-down menu and choose which algorithm you'd like to use. For more information, see "[Routing algorithms](#routing-algorithms)."
 ![Routing algorithm dropdown](/assets/images/help/teams/review-assignment-algorithm.png)
 9. Optionally, to always skip certain members of the team, select **Never assign certain team members**. Then, select one or more team members you'd like to always skip.
 ![Never assign certain team members checkbox and dropdown](/assets/images/help/teams/review-assignment-skip-members.png)
-10. Optionally, to only notify the team members chosen by code review assignment for each pull review request, under "Notifications" select **If assigning team members, don't notify the entire team.**
-![Code review assignment notifications](/assets/images/help/teams/review-assignment-notifications.png){% ifversion fpt or ghae or ghes > 3.2 or ghec %}
+{% ifversion fpt or ghec or ghae-next or ghes > 3.2 %}
 11. Optionally, to include members of child teams as potential reviewers when assigning requests, select **Child team members**.
 12. Optionally, to count any members whose review has already been requested against the total number of members to assign, select **Count existing requests**.
-13. Optionally, to remove the review request from the team when assigning team members, select **Team review request**.{% endif %}
+13. Optionally, to remove the review request from the team when assigning team members, select **Team review request**.
+{%- else %}
+10. Optionally, to only notify the team members chosen by code review assignment for each pull review request, under "Notifications" select **If assigning team members, don't notify the entire team.**
+{%- endif %}
 14. Click **Save changes**.
 
-## Disabling code review assignment
+## Disabling auto assignment
 {% data reusables.profile.access_org %}
 {% data reusables.user_settings.access_org %}
 {% data reusables.organizations.specific_team %}

content/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review.md

@@ -17,7 +17,7 @@ shortTitle: Request a PR review
 ---
 Owners and collaborators on a repository owned by a user account can assign pull request reviews. Organization members with triage permissions to a repository can assign a pull request review.
 
-Owners or collaborators can assign a pull request review to any person that has been explicitly granted [read access](/articles/access-permissions-on-github) to a user-owned repository. Organization members can assign a pull request review to any person or team with read access to a repository. The requested reviewer or team will receive a notification that you asked them to review the pull request. {% ifversion fpt or ghae or ghes or ghec %}If you request a review from a team and code review assignment is enabled, specific members will be requested and the team will be removed as a reviewer. For more information, see "[Managing code review assignment for your team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team)."{% endif %}
+Owners or collaborators can assign a pull request review to any person that has been explicitly granted [read access](/articles/access-permissions-on-github) to a user-owned repository. Organization members can assign a pull request review to any person or team with read access to a repository. The requested reviewer or team will receive a notification that you asked them to review the pull request. {% ifversion fpt or ghae or ghes or ghec %}If you request a review from a team and code review assignment is enabled, specific members will be requested and the team will be removed as a reviewer. For more information, see "[Managing code review settings for your team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)."{% endif %}
 
 {% note %}
 

content/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews.md

@@ -19,7 +19,7 @@ shortTitle: About PR reviews
 
 After a pull request is opened, anyone with *read* access can review and comment on the changes it proposes. You can also suggest specific changes to lines of code, which the author can apply directly from the pull request. For more information, see "[Reviewing proposed changes in a pull request](/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request)."
 
-Repository owners and collaborators can request a pull request review from a specific person. Organization members can also request a pull request review from a team with read access to the repository. For more information, see "[Requesting a pull request review](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review)." {% ifversion fpt or ghae or ghes or ghec %}You can specify a subset of team members to be automatically assigned in the place of the whole team. For more information, see "[Managing code review assignment for your team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team)."{% endif %}
+Repository owners and collaborators can request a pull request review from a specific person. Organization members can also request a pull request review from a team with read access to the repository. For more information, see "[Requesting a pull request review](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review)." {% ifversion fpt or ghae or ghes or ghec %}You can specify a subset of team members to be automatically assigned in the place of the whole team. For more information, see "[Managing code review settings for your team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)."{% endif %}
 
 Reviews allow for discussion of proposed changes and help ensure that the changes meet the repository's contributing guidelines and other quality standards. You can define which individuals or teams own certain types or areas of code in a CODEOWNERS file. When a pull request modifies code that has a defined owner, that individual or team will automatically be requested as a reviewer. For more information, see "[About code owners](/articles/about-code-owners/)."
 

content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners.md

@@ -25,7 +25,7 @@ Code owners are automatically requested for review when someone opens a pull req
 
 When someone with admin or owner permissions has enabled required reviews, they also can optionally require approval from a code owner before the author can merge a pull request in the repository. For more information, see "[About protected branches](/github/administering-a-repository/about-protected-branches#require-pull-request-reviews-before-merging)."
 
-{% ifversion fpt or ghae or ghes or ghec %}If a team has enabled code review assignments, the individual approvals won't satisfy the requirement for code owner approval in a protected branch. For more information, see "[Managing code review assignment for your team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team)."{% endif %}
+{% ifversion fpt or ghae or ghes or ghec %}If a team has enabled code review assignments, the individual approvals won't satisfy the requirement for code owner approval in a protected branch. For more information, see "[Managing code review settings for your team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team)."{% endif %}
 
 If a file has a code owner, you can see who the code owner is before you open a pull request. In the repository, you can browse to the file and hover over {% octicon "shield-lock" aria-label="The edit icon" %}.
 

data/features/only-notify-requested-members.yml

@@ -0,0 +1,7 @@
+# Issue #5108
+# Documentation for the "Only notify requested team members" option in the code review settings
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.4'
+  ghae: '*'

data/reusables/gated-features/code-review-assignment.md

@@ -1 +1 @@
-Code review assignment is available with {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_server %} 2.20+,{% ifversion ghae %} {% data variables.product.prodname_ghe_managed %},{% endif %} and {% data variables.product.prodname_ghe_cloud %}. For more information, see "[GitHub's products](/articles/githubs-products)."
+Code review settings are available with {% data variables.product.prodname_team %}, {% data variables.product.prodname_ghe_server %} 2.20+,{% ifversion ghae %} {% data variables.product.prodname_ghe_managed %},{% endif %} and {% data variables.product.prodname_ghe_cloud %}. For more information, see "[GitHub's products](/articles/githubs-products)."

data/reusables/organizations/team_maintainers_can.md

@@ -11,5 +11,5 @@ Members with team maintainer permissions can:
 - [Remove organization members from the team](/articles/removing-organization-members-from-a-team)
 - [Promote an existing team member to team maintainer](/organizations/organizing-members-into-teams/assigning-the-team-maintainer-role-to-a-team-member)
 - Remove the team's access to repositories{% ifversion fpt or ghes or ghae or ghec %}
-- [Manage code review assignment for the team](/organizations/organizing-members-into-teams/managing-code-review-assignment-for-your-team){% endif %}{% ifversion fpt or ghec %}
+- [Manage code review settings for the team](/organizations/organizing-members-into-teams/managing-code-review-settings-for-your-team){% endif %}{% ifversion fpt or ghec %}
 - [Manage scheduled reminders for pull requests](/github/setting-up-and-managing-organizations-and-teams/managing-scheduled-reminders-for-pull-requests){% endif %}