Project settings

This section describes how to use the new project settings page to view and edit project settings for a project. For more information about how to add a project, see Add a project.

To view or edit project settings for a specific project:

1. Click Projects in the menu.

2. Click on a project name displayed in My Projects list.

3. Click Settings in the menu.

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

   

   The following information is displayed in the project summary:

   • The name of the project.

   • The unique associated project identifier.

   • A Follow button that you can click to follow the project. This button is not available if you are a member of the project.

   • Total number of members, followers, and branches associated with the project.

   • A short description about the project.

Participants tab

To learn how to customize participants for a Helix Swarm project, watch this video or review the instructions following the video.

The Participants tab shows the following details:

Members

Displays a list of all the project members. This includes users, groups, and projects.

To add a project member:

1. Click Manage members button.

2. Select the Users, Groups, or Projects tab that you wish to add to the project members list.

3. Type in to search the name of a user, group, or project and click Add button.

To delete a project member, click the delete icon against their name.

Owners

Displays a list of all the project owners.

To add a project owner, click Manage owners button. Type in the name of the user you wish to add to the project owners list. The field auto-suggests users within Helix Core Server as you type. Click the Add button to add a user to the project owners list.

To delete a project owner, click the delete icon against their name.

Default reviewers

Displays a list of all the default reviewers. A default reviewer can be a user or a group.

To add a new default reviewer:

1. Click Manage default reviewers button.

2. Select the Users or Groups tab that you wish to add to the default reviewers list.

3. Type in to search the name and click Add button.

4. Click the drop-down box against the user or group name and select your desired option.

To edit your default reviewer preferences for an existing reviewer, click the drop-down box against the user name and select your desired option.

For a user, you can set the vote requirement to Optional or Required. When a group is a default reviewer, it can be set to operate in one of three ways:

• Optional:

  No members of the group are required to approve the review.

• Require one indicated by a star badge with a 1: 

  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 indicated by a star badge:

  All members of the group must up-vote the review to allow the review to be approved.

To delete a default reviewer, click the delete icon against their name.

To retain default reviewers, toggle the Retain default reviewers switch. For more details about retaining default reviewers, see Membership.

Followers

Displays a list of all the followers.

By default, project members and moderators are notified when a new review is started. Project members, moderators, and followers are notified when a change is committed.

Toggle the following switches at the bottom of the Participants tab to ensure which actions send a notification:

• Email members, moderators, and followers when a review is requested: When a new review is requested for the project, all project members and moderators of the project are added to the email notification list.
• Email members, moderators, and followers when a change is committed: When a change is committed for the project, all project members, project moderators and project followers of this project are added to the email notification list.

Branches tab

The Branches tab enables you to add a branch and configure the following options:

• Associate a workflow with the project branch

• Set minimum up votes

• Manage moderators

• Manage branch specific default reviewers

To learn how to create branches for a Helix Swarm project, watch this video or review the instructions following the video.

Add a branch

To add a branch:

1. Click the Add new branch button.

   The Add new branch dialog displays.

2. Enter a Name for your branch.

3. Enter one or more branch paths in the Depot paths field using depot syntax, one path per line.

   Tip

   • Branch paths, and files can be excluded by putting a minus symbol - at the start of the path.
   • Branch paths are processed in order, starting with the first file path in the list.

   For example:

   //depot/main/swarm/...

   -//depot/main/swarm/test/...

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

   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.

   Note

   • Wildcards should not be used; the only exception is that the branch path can end with the Helix Core Server wildcard ...
   • Branch paths are case sensitive.
   • Branch paths, and files are not checked to see if they are valid when you save the branch:
     • If you enter an invalid path ending in the wildcard ..., the path will not be displayed in the project file browser until the path is created. This allows you to specify a path before it has been created.
     • If you enter a path that ends with a file that has not been committed, or a non-existent file, Swarm displays a 404 error when you navigate the path to the file with the project file browser.
   Note

   The Project Commits tab can fail to show some Helix Core Server commits in the top level view. Individual branch views display the commits correctly:

   The Project Commits tab top level client view is made up of all of the branches of the project.

    

   For example, Project Alpha:

    

   Branch: QA:

   //depot/alpha/dev/QA/...

    

   Branch: Dev :

   //depot/alpha/dev/...

   -//depot/alpha/dev/QA/...

    

   The project commits tab view is generated by processing the branches in the order that they were created in and from top to bottom for the paths in each of those branches.

   For the project Alpha example above:

   The first path includes all of the directories and files under //depot/alpha/dev/QA/ in the project commits tab top level view.

   The second path includes all of the directories and files under //depot/alpha/dev/ in the project commits tab top level view.

   The third path excludes all of the directories and files in //depot/alpha/dev/QA/ from the project commits tab top level view.

    

   Result: commits made to //depot/alpha/dev/QA/ that should be shown for the QA branch are not displayed in the Project Commits tab top level view.

    

   When you have a simple branch structure this can be avoided by considering this issue when you create your branches. In the example above, creating the Dev branch first and then creating the QA branch avoids the problem because//depot/alpha/dev/QA/ is not excluded from the Project Commits tab top level view.

4. Click the Confirm button.

   A new branch is created.

   Note

   For multiple branches the most recently created branch is placed at the top.

Edit a branch

Expand the branch pane to view and further edit the branch settings as follows:

1. To associate a workflow, select the workflow from the Workflow dropdown list, or enter the workflow name in the search field. The field auto-suggests workflows as you type. Only workflows that you own and shared workflows are shown in the dropdown list.

   Tip

   • When a workflow is associated with a project, the workflow is used for all of the branches in that project.
   • When a project branch is associated with a workflow, the workflow of the parent project is ignored and the branch workflow is used.

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

   To use the parent project workflow, select Inherit from project from the Workflow dropdown list. This is the default when you create a new branch. If the parent project is set to No workflow, the branch will use the global workflow rules.

   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.

2. Set the Minimum Upvotes required for reviews associated with this branch.

   When Minimum up votes is set on a project, the project setting is used on the project branches unless Minimum up votes is set to 1 or higher on a branch. In this case the branch setting is used and the project setting is ignored.

   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.

   • If a review spans projects/branches, the Minimum up votes for each of the projects and branches must be satisfied before you can approve the review.
   • Required reviewers are included when up votes are counted.
   • When Count votes up from is set to Members for a workflow associated with a project/branch, only the up votes of members of the project contribute to satisfying the Minimum up votes for a project/branch. For more information about the Count votes up from rule, see Workflow rules.
   Important

   If the Workflow feature is disabled, all votes are counted not just votes from project members.

   Important

   If the Minimum up votes required is set higher than the number of reviewers that exist for a review, approval will be blocked for that review. This is true even if all the reviewers on the review have voted up the review.

3. Add moderators for a branch from the Branch moderators pane.

   Note

   This ensures that only moderators can approve or reject reviews.

   To add a moderator:

   1. Click Manage moderators button.

   2. Select the Users or Groups tab that you wish to add to the moderators list.

      If a group is specified as a moderator, all of the members of that group have the same moderator privileges for that project branch as if they were added individually.

   3. Type in to search the name of the user or group. The field auto-suggests groups and users within Helix Core Server as you type. Click Add button.

   When you add a moderator to a project branch, only the moderators can approve or reject reviews restriction is enabled for a project branch. Changing the state of any review associated with this 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.

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

4. Add default reviewers for a branch from the Default reviewers pane.

   Important

   When a review is part of multiple projects/project branches:

   • The default reviewer lists for all of the projects and project branches the review is part of are combined and added to the review.
   • If a default reviewer has different reviewer options set on projects and project branches that the review is part of, the strictest reviewer option is used for the review.
     

   Example: A review is created and it is part of Project A, Project B, and Project Branch b.

   Project A: default reviewer X is an Optional reviewer

   Project B: default reviewer X is an Optional reviewer

   Project Branch b: default reviewer X is a Required reviewer

   Result: default reviewer X is added to the review as a Required reviewer

   Note

   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.

   Note

   If a default reviewer is deleted from Helix Core Server they will not be added to new reviews.

   To add a default reviewer:

   1. Click Manage default reviewers button.

   2. Select the Users or Groups tab that you wish to add to the default reviewers list.

   3. Type in to search the name. The field auto-suggests groups and users within Helix Core Server as you type. Click Add button.

   Toggle the Retain default reviewers switch to prevent default reviewers being removed from reviews associated with this branch. For more information about retaining default reviewers, see Retain default reviewers.

   To delete a default reviewer, click the delete icon against their name.

Integrations tab

In the Integrations tab you can configure Automated tests and Automated deployment options.

To learn how to enable automated tests and deployment for a Helix Swarm project, watch this video or review the instructions following the video.

Automated tests

To enable or disable running automated tests for a project when reviews are created or updated, slide Automated tests toggle. When you wish to enable automated tests, enter a URL that triggers a test suite execution. Use the special arguments described in the dialog to help compose a URL that informs your test suite about important details.

Select the format of the POST parameters, either URL Encoded or JSON Encoded.

• URL Encoded: POST parameters are parsed into name=value pairs.

• JSON Encoded: parameters are passed raw in the POST body.

For more details about automated tests, see Automated testing for reviews.

Automated deployment

To enable or disable deploying a project when reviews are created or updated, slide the Automated deployment toggle. When you wish to enable automated deployment, enter a URL that triggers a deployment of the project's code. Use the special arguments described in the dialog to help compose a URL that informs your deployment program with important details. For more details about automated deployment, see Automatically deploy code within a review.

General Settings tab

To learn how to customize general settings of a Helix Swarm project, watch this video or review the instructions following the video.

In the General Settings tab, you can configure the following options:

1. Specify a project name.

2. Add a short description about the project.

3. Select a Workflow to associate with the project. Your selection is auto saved.

   Note

   The Workflow option is not displayed if the workflow feature is disabled.

   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.

   To associate a workflow, select the workflow from the Workflow dropdown list, or enter the workflow name in the search field. The field auto-suggests workflows as you type. Only workflows that you own and shared workflows are shown in the dropdown list.

   Tip

   • When a workflow is associated with a project, the workflow is used for all of the branches in that project.
   • When a project branch is associated with a workflow, the workflow of the parent project is ignored and the branch workflow is used.

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

4. Set the Minimum up votes for a project. The project setting is used on the project branches unless Minimum up votes is set to 1 or higher on a branch. In this case the branch setting is used and the project setting is ignored.

   Enter the Minimum up votes or use the up and down arrow keys to increase or decrease the number of Minimum up votes. To save your changes click the green tick icon. Click the cross icon to delete your changes.

   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.

   • If a review spans projects/branches, the Minimum up votes for each of the projects and branches must be satisfied before you can approve the review.
   • Required reviewers are included when up votes are counted.
   • When Count votes up from is set to Members for a workflow associated with a project/branch, only the up votes of members of the project contribute to satisfying the Minimum up votes for a project/branch. For more information about the Count votes up from rule, see Workflow rules.
   Important

   If the Workflow feature is disabled, all votes are counted not just votes from project members.

   Important

   If the Minimum up votes required is set higher than the number of reviewers that exist for a review, approval will be blocked for that review. This is true even if all the reviewers on the review have voted up the review.

5. Specify a Job filter.

   The job filter allows you to specify criteria that are used to associate jobs with projects. For example, entering Subsystem=ProjectA associates jobs whose subsystem field is set to ProjectA with the current project.

   Note

   This job filter is simpler than the filters available in other Helix Core Server clients. The filter must be expressed as field=value pairs; bare keywords are not permitted. The asterisk for wildcard matching is permitted, but no other filter expression syntax is permitted.

6. Slide the Private project toggle to make this project private. Private projects and their associated reviews are only visible to project owners, moderators, and members, plus users with super privileges in Helix Core Server.

   For more information, see Private projects.

7. Delete a project as follows:

   Note

   For more information about deleting a project, see Delete a project.

   1. Click Delete Project.

      A confirmation dialog appears to confirm whether you want to delete this project.

   2. Click Confirm to delete the project.