Workflow overview

A workflow can be applied to a project In Helix Swarm, a group of Helix Core Server users who are working together on a specific codebase, defined by one or more branches of code, along with options for a job filter, automated test integration, and automated deployment. or project branch to ensure that changelists and reviews in the project/branch follow the rules specified in that workflow. The Workflow basics section gives an overview of global workflow rules, workflow rules and how they interact with each other.

Sections in this chapter:

• Workflow rules.
• Workflow basics.
• Example workflows.
• Merging multiple workflows.

Workflow rules

A workflow is made up of the following workflow rules:

On commit without a review:

This rule is applied when a changelist without an associated review is submitted from outside of Swarm.

Select one of the following options:

• Allow: the changelist is not checked, the changelist is submitted without a review.
• Create a review: the changelist is submitted and a review is created automatically for the changelist.
• Reject: the changelist submit is rejected.
Tip

The selected rule is also applied when a changelist is submitted with #review in the description.

On commit with a review: This rule is applied when:

• A Swarm review is committed.
• A changelist with an associated review is submitted from outside of Swarm.

Select one of the following options:

• Allow: the changelist review state is not checked. The changelist is committed even if its associated review is not approved.
• Reject unless approved: the changelist is only submitted if its associated review is approved and the content of the changelist is identical to the content of the approved review.
Tip

The selected rule is also applied when a changelist is submitted with #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID). For more information about adding a changelist to a review by including a keyword in the changelist description, see Review creation, and modification outside of Swarm.

On update of a review in an end state:

Used to stop review content being automatically changed for reviews that are in specific states. By default, the protected end states are Archived, Rejected, and Approve:Commit. The end states are set by the Swarm administrator.

This rule is applied when a changelist is added to a review.

Select one of the following options

• Allow: the review is not checked. The changelist is added to the review no matter what the review state is. This is the default setting.
• Reject: if the review is in one of the states specified in the end_state configurable:
  • The Add Change button is disabled for the review.
  • The changelist is rejected if it is added outside of Swarm using #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID).

Count votes up from:

By default, all of the up votes on a review are counted for the Minimum up votes value set on the project/branch the review is associated with. Limit the up votes that are counted to just the members of the project the review is associated with by using this rule.

This rule is applied when a user votes on a review.

Select one of the following options:

• Anyone: votes are counted for all reviewers on a review. This is the default setting.
• Members: only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.

Automatically approve reviews:

By default, reviews must be manually approved. Enable automatic approval of reviews with this rule.

This rule is applied when a user votes on a review.

Select one of the following options:

• Never: reviews are not automatically approved. This is the default setting.
• Based on vote count: reviews are automatically approved if:
  • There are no down votes on the review.
  • There are no moderators on the review. If a review has moderators it cannot be automatically approved.
  • All of the Required reviewers on the review have voted up.
  • The Minimum up votes on the review has been satisfied for each of the projects and branches the review spans.
  • All of the tests configured to block approval have passed.
  Important

  Moderators prevent the automatic approval of reviews. For more information about moderators, see Moderators.

  Tip

  After a review has been automatically approved it needs to be manually committed.

For information about creating a new workflow, see Create a workflow.

Workflow basics

• Workflows: can be associated with projects and/or project branches.
  • A workflow can be created by any Swarm user.
  • If a workflow is associated with any projects or project branches, that workflow cannot be deleted.
  • A workflow can be shared by the workflow owner.
  • A shared workflow can be viewed by any Swarm user.
  • A shared workflow can be applied to a project or project branch by any Swarm user that is authorized to edit the project.
  • If sharing is switched off for a workflow, any projects or branches associated with that workflow will remain associated with it.
• Projects and branches:
  • 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. The project workflow is replaced by the branch workflow, the workflows are not merged. For examples of why you might use this, see Restrictive project workflow with a less restrictive development branch workflow, and Project workflow with a more restrictive release branch workflow.
  • When a branch is associated with a workflow and a global workflow rule is set to Enforce on by the administrator, the workflow of the parent project is ignored and the global workflow rule is merged with the branch workflow. The most restrictive rule is used.
• Modifying a workflow:
  • If a global workflow rule is set to Enforce off and that rule is modified, projects and branches that do not have an associated workflow will use the modified rule.
  • If a global workflow rule is set to Enforce on and the rule is modified, the entire Helix Core Server will use the modified rule.
  • If a workflow is modified, any projects or branches associated with that workflow will use the modified workflow.
• Global workflow rules: configured by the Swarm administrator in Workflow global rules, each rule can be set in one of two modes:
  • Enforce off: the global workflow rule is used for projects and branches that do not have an associated workflow.
    • If a project or branch has an associated workflow, the global rule is ignored for that project or branch.
    • If projects are not used, the global workflow rule applies to the entire Helix Core Server.
  • Enforce on: the global workflow rule is used for the entire Helix Core Server. This allows a minimum workflow to be set for the Helix Core Server.
    • The global workflow rule is merged with the workflow associated with a project or branch. The most restrictive rule is used.
• Tests:
  • If a test is associated with a workflow, it can be configured to run when a review associated with that workflow is either created/updated or submitted, or run manually from the review.
  • If a test is associated with the global workflow, it can be configured to run when a review is either created/updated or submitted, or run on manually from the review.
  • If a test is associated with a workflow or a global workflow, it can be configured to block approval if it fails.

Example workflows

This section contains examples of typical workflows that can be configured in Swarm.

Enforce a pre-commit review workflow

To enforce a pre-commit review workflow set the rules to:

• On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
• On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.

Allow a post-commit review workflow

To allow a post-commit review workflow set the rules to:

• On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
• On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.

Restrictive project workflow with a less restrictive development branch workflow

The release and main branches need a restrictive workflow to protect the codelines. All submissions must have an associated approved review and the content of the changelist must be identical to the content of the approved review.

The development branch can be less restrictive because you want to get features in quickly and review them after they have been committed. In this scenario you would probably want to ensure that all submitted changelists have an associated review.

Project workflow:

• On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
• On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.
• On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
• Count votes up from: set to Members, ensures that only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.
• Automatically approve reviews: set to Never, ensures that reviews are not automatically approved.

Development branch workflow:

• On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
• On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.
• On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
• Count votes up from: set to Anyone, ensures that votes of all reviewers on a review are counted for the Minimum up votes set on projects/branches.
• Automatically approve reviews: set to Based on vote count, ensures that reviews are automatically approved when all of the review requirements have been satisfied.

Project workflow with a more restrictive release branch workflow

The project is set up with workflow that allows post commit reviews, this allows you to get features in quickly and review them after they have been committed. In this scenario it is a good idea make all submitted changelists have an associated review.

The release branch needs a more restrictive workflow to protect the codeline. All submissions must have an associated approved review and the content of the changelist must be identical to the content of the approved review.

Project workflow: defines the workflow for the project and its branches.

• On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
• On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.
• On update of a review in an end state: set to Allow, allows the content of reviews that are considered complete to be changed.
• Count votes up from: set to Anyone, ensures that votes of all reviewers on a review are counted for the Minimum up votes set on projects/branches.
• Automatically approve reviews: set to Based on vote count, ensures that reviews are automatically approved when all of the review requirements have been satisfied.

Release branch workflow: defines the workflow for the release branch. The workflow of the parent project is ignored and the development branch workflow is used.

• On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
• On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.
• On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
• Count votes up from: set to Members, ensures that only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.
• Automatically approve reviews: set to Never, ensures that reviews are not automatically approved.

Merging multiple workflows

If a changelist spans multiple projects that have different workflows, the workflows are merged and the most restrictive workflow rules are used for the changelist. All of the tests associated with the merged workflows are run. If there are any duplicate tests they are only run once.

Example 1: Changelist 1234 spans Project A, Project B, and Project C

• Project A: //depot/jam/lib/...
• Project B: //depot/jam/docs/...
• Project C: //depot/common/src/...
• Changelist 1234 contains the following files:
  • //depot/jam/lib/tests/checkLoad.sh
  • //depot/jam/docs/basics.workflow.html
  • //depot/common/src/index.html

The files span all three locations so the changelist is subject to the combined workflow rules for the three locations. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews	Workflow Tests
Project A workflow	Allow	Reject unless approved	Allow	Anyone	Based on vote count	Smoke Test A
Project B workflow	Allow	Reject unless approved	Reject	Members	Never	Smoke Test B
Project C workflow	Create a review	Allow	Allow	Anyone	Based on vote count	Smoke Test B Smoke Test C
Changelist 1234 workflow	Create a review	Reject unless approved	Reject	Members	Never	Smoke Test A Smoke Test B Smoke Test C

Example 2: Changelist 6789 spans Project M, Project N, and Project branch N-1

• Project M: //depot/thirdparty/lib/...
• Project N: //depot/thirdparty/lib/tests/...
• Project branch N-1:
  • //depot/projectN/...
  • //depot/thirdparty/lib/...
• Changelist 6789 contains the following files:
  • //depot/thirdparty/lib/tests/checkReturns.sh
  • //depot/projectN/src/index.html
  • //depot/projectN/tests/pageLoadTest.php

The changelist files span all three locations so the changelist is subject to the combined workflow rules for the three locations. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews	Workflow Tests
Project M workflow	Create a review	Reject unless approved	Allow	Anyone	Never	Smoke Test M
Project N workflow	Reject	Reject unless approved	Reject	Members	Never	Smoke Test N
Project branch N-1 workflow	Create a review	Allow	Allow	Anyone	Based on vote count	Smoke Test N-1
Changelist 6789 workflow	Create a review	Reject unless approved	Allow	Anyone	Never	Smoke Test M Smoke Test N-1

Example 3: Changelist 3456 spans Project X, and Project Y

• Project X: //depot/main/product/...
• Project Y: //depot/main/product/docs/...
• Changelist 3456 contains the following files:
  • //depot/main/product/tests/fileSelector.sh
  • //depot/main/product/docs/admin.html

The changelist files span both locations so the changelist is subject to the combined workflow rules for the two locations, and the Global workflow rules set by the administrator. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews	Workflow Tests
Project X workflow	Create a review	Allow	Allow	Anyone	Based on vote count	Smoke Test X
Project Y workflow	Reject	Allow	Reject	Anyone	Based on vote count	Smoke Test Y
Global workflow rules	Create a review (Enforce on)	Reject unless approved (Enforce off)	Allow (Enforce on)	Members (Enforce on)	Never (Enforce off)	Global Smoke Test Global Full Test
Changelist 3456 workflow	Reject	Allow	Reject	Members	Based on vote count	Smoke Test X Smoke Test Y Global Smoke Test Global Full Test