Helix Swarm Guide (2020.1)

Responsibility

Initially, code reviews have no reviewers.

User and group default reviewers can be set for individual projects and project branches. Each time a new review is created in the project or project branch, the default reviewers will be added to the review. See default reviewers for details.

Code review authors can designate users as reviewers by including an @mention for each desired reviewer, and an @*mention for each required reviewer. They can also designate groups as reviewers by using @@mention for each desired group reviewer, an @@*mention for each required reviewer group (all members required), and an @@!mention for each required reviewer group (one vote required). Code review authors can also designate users or groups as reviewers by using the Edit Reviewers dialog which allows reviewers to be added, removed, and to configure the reviewer type.

Other users can show their interest in participating in the code review by clicking their own avatar in the Reviewers area of the code review and selecting Join review, or by commenting on a review or one of its files. Once a user shows such interest, they are added to the review's list of reviewers and share in the responsibility of performing the code review. Later on, reviewers can change whether their vote is required or optional, or leave a review (perhaps to prevent further notifications).

Looking at a review list can help you determine which reviews have likely not been started, using the No Reviewers filter. Once a review has reviewers, it is considered to be active and appears in the review list with the state Has Reviewers.

Review participation is advisory by default, and is used to inform your team that a code review is being conducted. The disposition of the review is reflected in the review's current state, the badges that may appear over each reviewer's avatar, and any comments reviewers might add.

Moderators

A project moderator is a user assigned to moderate reviews for a specific branch associated with a project.

When the Only Moderators can approve or reject reviews restriction is enabled for a project branch, that branch is moderated. See Add a project for details on adding moderators to project branches.

Changing the state of any review associated with a moderated branch is restricted as follows:

  • Only moderators can approve or reject the review. Moderators can also transition a review to any other state.
  • Important

    Moderators prevent the automatic approval of reviews, for more information about automatically approving reviews using workflow rules see Workflow rules.

    Note

    By default, when a review spans multiple branches that have different moderators, only one moderator from any one of the branches needs to approve the review.

    Swarm can be configured to require that one moderator from each branch must approve the review, this is a global setting. If a moderator belongs to more than one of the branches spanned by the review, their approval will count for each of the branches they belong to. For instructions on how to configure moderator behavior, see Moderator behavior when a review spans multiple branches.

  • The review's author, when not a moderator, can change the review's state to Needs Review, Needs Revision, Archived, and can attach committed changelists.

    Normally, the review's author cannot change the review's state to Approved or Rejected on moderated branches. However, authors that are also moderators have moderator privileges, and may approve or reject their own review.

    When disable_self_approve is enabled, authors who are moderators (or even users with admin privileges) cannot approve their own reviews.

  • Project members can change the review's state to Needs Review or Needs Revision, and can attach committed changelists. Project members cannot change the review's state to Approved, Rejected, or Archived.
  • Users that are not project members, moderators, or the review's author cannot transition the review's state.
  • For the review's author and project members, if a review is not in one of their permitted states, for example if the review's state is Rejected, they cannot transition the review to another state.

These restrictions have no effect on who can start a review.

Required reviewers

Reviews can optionally have required reviewers. When a review has required reviewers, the review cannot be approved until all required reviewers and required reviewer groups have up-voted the review. If the review is associated with a project that has assigned moderators, even the moderators cannot approve the review without up-votes from all required reviewers (but they can reject the review).

When a group is a required reviewer, it can be set to operate in one of two ways:

  • All votes required: all members of the group must up-vote the review to allow the review to be approved.
  • One vote required: at least one member of the group must up-vote the review to allow the review to be approved. If any member of the group down-votes the review, the review cannot be approved.

Required reviewers are expected to take greater care while performing a review than non-required reviewers, as their votes affect whether a review can be approved or not.

To edit the reviewers for a review, and to change whether a reviewer is required or not, see Edit reviewers.

Note

If a review involves a branch with assigned moderators, only a moderator can approve the review, even if all required reviewers have up-voted the review.

See Add a project for details on adding moderators to project branches.

Add yourself as a reviewer

  1. Visit the review's page.
  2. Log in, if you have not already done so.
  3. Click your avatar in the Reviewers area of the review display, which should be grayed out since you are not yet a reviewer. A dropdown menu appears.
  4. Select + Join Review. Alternatively, you can select ^ Vote Up or v Vote Down if you approve or disapprove of the review, respectively; either will cast your vote and make you a reviewer.

Your avatar is no longer grayed out, and you are now a reviewer.

Remove yourself as a reviewer

  1. Visit the review's page.
  2. Log in, if you have not already done so.
  3. Click your avatar in the Reviewers area of the review display, which should not be grayed out since you are already a reviewer. A dropdown menu appears.
  4. Select X Leave Review.

Your avatar is now grayed out, and you are no longer a reviewer.