Manage project branches

Initial steps:

1. Visit your project page.

2. Click Settings in the menu.

   A project summary with Participants tab, Branches tab, Integrations tab, and General Settings tab is displayed.

3. Click Branches tab.

Here you can view and create project branches.

Adding a branch

1. Click the Add new branch button. This opens an Add new branch dialog.

   

2. Enter a short Name for your branch.

3. Enter one or more branch paths in the Depot paths field using depot syntax, one path per line. For more information on branch paths, see Example branch paths.

   Branch paths are case sensitive.

4. Click the Confirm button.

A new branch is created.

Example branch paths

If you have entered multiple branch paths into the Depot paths field, these paths are processed in order, starting with the first path in the list.

Branch paths, and files can be excluded by putting a minus symbol - at the start of the path. In the following example:

• The first path includes all of the directories and files under //depot/main/swarm/ in the project branch.

• The second path excludes all of the files in -//depot/main/swarm/test/ from the project branch.

• The third path includes the ResultSummary.html file from the previously excluded //depot/main/swarm/test/ directory.

//depot/main/swarm/...
-//depot/main/swarm/test/...
//depot/main/swarm/test/ResultSummary.html

Wildcards are supported in the project branch paths. For more information, see Wildcards in branch paths.

Edit a branch

Once you have created a branch, additional options become available for managing the branch further. Click on the name of the branch to expand the branch pane to view the additional options. All settings described in this section are optional.

Workflow

You can associate a workflow with the project branch. If you have disabled the workflow feature, this option will not be displayed.

To associate a workflow with a project branch, select one from the Workflow dropdown list, or enter the workflow name in the search field. You will only be able to see the workflows that you own or shared workflows. When a workflow is associated with a project, the workflow is used for all of the branches in that project.

To use the parent project workflow, select Inherit from project from the Workflow dropdown list. This option is select by default when you create a new branch. If the parent project is set to No workflow, the branch will use the global workflow rules. When a project branch is associated with a workflow, the workflow of the parent project is ignored and the branch workflow is used.

To remove the existing workflow without replacing it with another workflow, select No Workflow from the Workflow dropdown list. This is the default when you create a new project.

For more information about workflows and how project workflows interact with branch workflows, see Workflow basics.

Minimum up votes

Use Minimum up votes to set the minimum number of up votes required for reviews in this branch.

A review cannot be approved until all of the Required reviewers have voted up the review and the Minimum up votes specified has been satisfied.

When this setting is defined at the project level, minimum number of up votes is automatically applied to all branches. However, if you set Minimum up votes to 1 or higher on a specific branch, that branch will use its own setting and ignore the project-level setting.

To use the project-level value, set Minimum up votes to Inherit from project. This is set by default for new branches.

To override the project setting and use a custom value for a certain branch, set Minimum up votes to 1 or higher on that branch.

Notes on minimum up votes

• If a review includes changes across multiple projects or branches, the minimum number of up votes on each project or branch must be met before the review can be approved.

• Required reviewers are included when counting up votes.

• When the workflow rule Count votes up from is set to Members for a project or branch, only up votes from members belong to that project or branch will count toward the minimum up votes requirement. For more information on the Count votes up from rule, see Workflow rules.

  If workflows are disabled, all votes are counted, not just votes from project members.

Branch moderators

Only moderators can approve or reject reviews on the branch.

To add moderators to a branch:

1. Click the Manage moderators button.

2. Choose the Users or Groups tab.

   1. If you selected Users, start typing a the name of a user. Suggested users on the P4 Server will appear automatically.

   2. If you selected groups, then all of the members of that group will have the same moderator privileges for that project branch. Use this option if you wanted to add several users at once.

3. Click Add.

After you finish setting up the branch and save the project, reviews on this branch can only be approved or rejected by moderators.

Moderators can also transition a review to any other state. Below is a summary of branch moderator roles and review state rules.

Additional notes

• Moderators can prevent automatic approvals. For more information about automatically approving reviews using workflow rules see Workflow rules.

• By default, if a review spans multiple branches with different moderators, only one moderator from any branch needs to approve it. You can change this (via a global setting) to require one moderator per branch. If a moderator belongs to multiple branches, one approval counts for each. For instructions on how to configure moderator behavior, see Moderator behavior when a review spans multiple branches.

To delete a moderator, click the delete icon against their name.

Default reviewers

You can add default reviewers in the Default reviewers pane. To add a default reviewer:

1. Click the Manage default reviewers button.

2. Choose the Users or Groups tab.

   1. If you selected Users, start typing a the name of a user. Suggested users will appear automatically.

   2. If you selected groups, then all of the members of the selected group will be added as a default reviewer.

      You can add up to 25 users or groups combined.

3. Click Add.

From now on, each new review on this branch will automatically include these reviewers.

To keep default reviewers from being removed on reviews for this branch, turn on Retain default reviewers. For more information about retained default reviewers, see Retain default reviewers.

After you add default reviewers, you can control whether their votes are required or optional for approving a review. This is done using the Vote Requirement column.

For users, select on of the following vote requirements.

• Optional - This users vote is not required to approve a review.

• Required - This users vote is required to approve a review

For groups, select on of the following vote requirements.

• Optional - The vote from users in this group is not required to approve a review.

• Required one - At least one member of the group must approve the review, and no member votes down the review either.

• Required all - All members of the group must vote up the review to approve it.

Default reviewers for reviews in multiple projects or branches:

When a review belongs to more than one project or branch:

• The default reviewers from all the related projects and branches are combined and added to the review.

• If a reviewer has different vote requirements in different places, the strictest setting is used.

For example:

• In Project-A, Reviewer X is optional.

• In Project-B, Reviewer X is optional.

• In the project branch, Branch-b, Reviewer X is required.

As a result, Reviewer X will be added as a required reviewer on the review.

Mentioning default reviewers

If users or groups are @mentioned in a new changelist description that includes #review, they will be added to the review as reviewers. If any of these reviewers are already specified as default reviewers they will not be added to the review again, the reviewer's most restrictive reviewer option is used for the review.

To remove a user or group as a default reviewer, click the delete icon in their row of the table.

Removing a branch

1. Follow the initial steps.
2. Expand the branch pane you want to delete.
3. Click Delete Branch.

   A confirmation dialog appears.

4. Click Yes to delete the branch.