Workflow: a step-by-step walk-through

This chapter shows an example of the workflow for a project using the Mainline model and step-by-step instructions for creating and using a Swarm workflow.

Mainline model workflow example

As a project owner you want to setup a project using the Mainline model with 'development', 'main' and 'release' branches. Each of these branches will have workflow rules that are tailored to its branch type.

Typically, you want your development branch to allow quick changes to the project content so that it can be populated quickly. Breaking test is acceptable at this point in the project. It is usually acceptable for a review to be raised after the content has been committed, this is the post-review commit model. Often you would only require one reviewer to vote up a review to trigger automatic approval. This minimal workflow configuration helps the development line to be built up quickly.

For your main branch you probably want to enforce pre-commit reviews, require more reviewers to vote up a review to trigger automatic approval, and restrict the up votes to project members only. This all helps to increase the stability of the main branch.

For a release branch you want even more protection for the content of the branch by only allowing critical changes to be committed to the branch. This is controlled by adding senior project members as moderators to the branch. Moderators are the only users that can approve or reject a review so they act as the gatekeepers for the branch. Moderators are added to the branch from the project branch settings pane.

Development branch example:

A Development branch needs to be fast moving, allowing new features, collateral, and technologies to be added very quickly with issues fixed as they occur. In essence this is rapid development allowing a lot of work to be completed quickly but the branch is unstable. The workflow for your development branch would be configured to allow for this style of working, typically:

• The branch rules allow post-commit and pre-commit reviews as required:
  • Changes can be committed and a review can be requested later, this is a post-commit review. This approach is particularly useful if you are making large changes and you just want to get content into the depot and then check it.
  • Changes can be shelved with a review, this is a pre-commit review. This is useful when a user is adding standalone content or a feature that needs to be approved before it is committed to the depot.
• Only one reviewer needs to vote up a review to trigger automatic approval.

Main branch example:

A main branch needs to be more tightly controlled than the development branch as it is more stable as you move towards release. In essence, the main branch is used to fix any lingering issues and firm up the content and any tests you have in place. The workflow for your main branch would be configured to allow for this style of working, typically:

• Changelists must be shelved with a review, this is a pre-commit review.
• Up votes for reviews are only counted from project members.
• Two reviewers from the project are required to vote up a review to trigger automatic approval.
• The changelist can only be committed if the content of the changelist is identical to the content of the approved review.

Release branch example:

A Release branch typically needs to be very tightly controlled to protect the codeline with only a select set of users empowered to approve and commit reviews to the project before the product is released. In essence, the branch should be stable and you should not be making changes unless absolutely necessary. The workflow for your release branch would be configured to allow for this style of working, typically:

• Changelists must be shelved with a review, this is a pre-commit review.
• Senior members of the project are required to vote up the review before it can be approved.
• Moderators act as the final gatekeepers for review approval, only they have the power to approve a review once the required reviewers have voted the review up.
• The changelist can only be committed if the content of the changelist is identical to the content of the approved review.
• Approval is blocked if specific tests fail.

These are three very different workflows, it is easy for team members to forget the rules especially when they are new to the project or team. Swarm workflows enable you to enforce your rules and control your branches more effectively. No more last minute changes breaking your release build and no more post-commit reviews in your pre-commit world.

Step-by-step walk-through example

The workflow we will create and use for this step-by-step walk-through enforces the pre-commit review model. This means that all changelists must be reviewed and approved before they can be committed to the depot.

Basic workflow and project settings used in the step-by-step walk-through:

• Review voting requirements:
  • If the review has any down votes it cannot be approved.
  • All of the required reviewers must vote the review up.
  • At least three project members must vote up the review, this includes the required reviewers.
• Swarm automatically approves a review when all of the voting requirements are satisfied.
• Changelist submit restrictions:
  • If a changelist is submitted without a review, the changelist submit is rejected.
  • If a changelist is submitted without an approved review, the changelist submit is rejected.
• If a review is in any of the following states: Archived, Rejected, and Approve:Commit it cannot be updated.

Sections in this chapter: