Workflow global rules - Technology preview feature

Warning

Workflow is a technology preview feature and is disabled by default.

This section provides information on how to enable workflow and configure the global workflow rules for Swarm.

Each global workflow rule has a mode setting, this determines how that rule is used by Swarm:

Default mode: applies the workflow rule setting to projects and project branches that don't have an associated workflow. If a project or project branch has an associated Swarm workflow, the global rule is ignored.
Policy mode: applies a minimum workflow rule setting to all projects and project branches. If a project or project branch has an associated workflow, the global rule is merged with the workflow rule and the most restrictive setting is used.

Important

Changes to global workflow rules that are set to default mode will change the workflow for projects and project branches that do not have an associated workflow.
Changes to global workflow rules that are set to policy mode will change the workflow for all projects and project branches.

Configure the global workflow rules with the following configuration block in the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'workflow' => array(    
        'enabled' => false, // Switches the workflow feature on. Workflow is a technology preview feature, it is currently unsupported and not suitable for production. Default is false
    ),
    'workflow_rules' => array(
        'on_submit'  => array(
            'with_review'    => array(
                'rule' => 'no_checking', // 'no_checking|strict'
                'mode' => 'default' // 'policy|default'
            ),
            'without_review' => array(
                'rule' => 'no_checking', // 'no_checking|auto_create|reject'
                'mode' => 'default' // 'policy|default' 
            ),
        ), 
        'end_rules' => array(
            'update' => array(
                'rule' => 'no_checking', // 'no_checking|no_revision'
                'mode' => 'default' // 'policy|default'
            ),
        ),
        'counted_votes' => array(
            'rule' => 'anyone', // 'anyone|members'
            'mode' => 'default' // 'policy|default'
        ),
        'auto_approve' => array(
            'rule' => 'never', // 'never|votes'
            'mode' => 'default' // 'policy|default'
        ),
    ),

workflow

Warning

Workflow is a technology preview feature and is disabled by default.

Technology preview features:

Technology Preview features are currently unsupported, might not be functionally complete, and are not suitable for deployment in production. Technology preview features are subject to change and may be removed before they become fully supported features.

These features are provided to the customer to solicit interest and feedback, with the goal of full support in future releases. Customers are encouraged to provide feedback and functionality suggestions for Technology Preview features before they become fully supported.

To enable the workflow feature, edit the SWARM_ROOT/data/config.php file and set the enabled configurable to true in the workflow section of the codeblock:

    'workflow' => array(    
        'enabled' => false, // Switches the workflow feature on. Workflow is a technology preview feature, it is currently unsupported and not suitable for production. Default is false
    ),

The default value is false.

with_review

with_review: applied when:

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

Tip

The with_review 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 Add a changelist to a review.

rule: choose one of the following options:
- no_checking: the changelist review state is not checked. The changelist is committed even if its associated review is not approved. This is the default rule.
- strict: the changelist review state is checked to see if the review is in an approved state (check performed during the change-submit trigger event). A further check is made to see if the content of the changelist is identical to the content of the approved review (check performed during the change-content trigger event).
  - Review is approved and changelist content is identical to the approved review: the changelist is submitted.
  - Review is approved and the changelist content is not identical to the approved review: the changelist submit is rejected.
  - Review is not approved: the changelist submit is rejected.
mode: choose one of the following options:
- default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
- policy: the rule is applied to all projects and project branches even if there is an associated workflow.

without_review

without_review: applied when a changelist without an associated review is submitted from outside of Swarm.

Tip

The without_review rule is also applied when a changelist is submitted with #review in the description. For more information about creating a review by including a keyword in the changelist description, see Create a review.

rule: choose one of the following options:
- no_checking: the changelist is not checked, the changelist is submitted without a review. This is the default rule.
- auto_create: the changelist is submitted and a review is created automatically for the changelist.
- reject: the changelist submit is rejected.
mode: choose one of the following options:
- default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
- policy: the rule is applied to all projects and project branches even if there is an associated workflow.

end_rules

By default, you can update the content of a review no matter what state the review is in. Reviews can be protected from content change if they are in a specified state by using the end_states configurable.

The end_states configurable sets the protected review states.

update: applied when a changelist is added to a review.

rule: choose one of the following options:
- no_checking: the review is not checked, the changelist is added to the review no matter what the review state is. This is the default setting.
- no_revision: if the review is in one of the states specified in the end_state configurable (check performed during the shelve-submit, and change-submit trigger events):
  - The Add Change button is disabled for the review.
  - The changelist is rejected if it is added outside of Swarm by adding #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the changelist description (nnnnn = review ID).
mode: choose one of the following options:
- default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
- policy: the rule is applied to all projects and project branches even if there is an associated workflow.

counted_votes

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.

counted_votes: applied when a user votes on a review.

rule: choose 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.
mode: choose one of the following options:
- default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
- policy: the rule is applied to all projects and project branches even if there is an associated workflow.

Tip

For instructions on how to set Minimum up votes for projects and branches, see Project minimum up votes and Branch minimum up votes.

auto_approve

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

auto_approve: applied when a user votes on a review, a required reviewer is added to a review, or a required reviewer is made an optional reviewer on a review.

rule: choose one of the following options:
- never: reviews are not automatically approved. This is the default setting.
- votes: 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.
  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.
mode: choose one of the following options:
- default: the rule is only applied to a project or project branch that does not have an associated workflow. This is the default mode.
- policy: the rule is applied to all projects and project branches even if there is an associated workflow.