Review cleanup

When a review is created in Swarm, it creates its own version of the changelist, leaving the user's own changelist untouched so as not to interfere with the user's ongoing work. Each time new work is submitted to the review, Swarm creates a new changelist so that there is a versioned history of the review.

When the review is finally committed it is Swarm's own changelist that is committed. Swarm's changelists are generally hidden from the users, but the user's changelist will remain open. By default it is necessary for the user to tidy up and remove this changelist themselves after the review has been completed.

There is an option to do this automatically when the review is committed. Configuration for this is expressed with a reviews block in the SWARM_ROOT/data/config.php file, similar to the following example: 

<?php
  'reviews' => array(
      'cleanup'              => array(
          'mode'        => 'user', // auto - follow default, user - present checkbox(with default)
          'default'     => false,  // clean up pending changelists on commit
          'reopenFiles' => false   // re-open any opened files into the default changelist
      ),
  ),

By default, this option is enabled but defaults to no clean up (so a user can select the option if they want to when they commit a review).

If the Helix user that Swarm is configured to use is a super user, then the user can clean up all user changelists associated with a review. If this is not the case, then the user who commits a review can only clean up changelists that are in their name.

By default, Swarm only cleans up changelists that are owned by the commiting user. In the case where a user is commiting a review that has been contributed to by other users, their changelists will not be cleaned up.

If you want to configure Swarm to clean up all changelists contributing to a review, regardless of whether they are owned by the commiting user, you can do this by granting the Helix user that Swarm is configured as 'super' permissions/privileges (rather than just the 'admin' permissions/privileges that swarm requires for its other operations).

Note

There is an API option that allows full cleanup to be executed with super permissions using an external script. This removes the need for the Swarm Helix user to have super privileges. See the API notes for details on this.

mode

If the mode is 'user' then a checkbox is displayed when a review is committed, and the user has the option as to whether to clean up changelists or not.

If the mode is 'auto', then no checkbox is displayed, and all committed reviews will either always be tidied up, or never will be, depending on the value of default.

default

If mode is set to 'user', then this determines whether the checkbox shown on commit is ticked by default or not.

If mode is set to auto then it determines the action to be taken automatically. If set to true then changelists will always be cleaned up, otherwise they will never be cleaned up.

reopenFiles

If a changelist has files checked out (not shelved), then it cannot be deleted. Setting reopenFiles to true will mean that when a changelist is cleaned up, any opened files will first be moved to the default changelist, allowing the changelist to be removed.

If set to false, then a changelist with checked out files will not be cleaned up.

If users normally revert their files after shelving them, then this option may not be needed. If set to true then it may result in files appearing in the user's default changelist unexpectedly.

The review cleanup feature is designed to help users keep their workspaces clean, and prevent the proliferation of unwanted changelists after reviews have been approved and committed.

However, it cannot guarantee to be perfect, and because it is taking actions automatically on the part of the user, it may do things that the user doesn't expect. The following caveats should be kept in mind when using this feature.

  • The changelists created by Swarm itself will not be touched by this process. There will always be a record of the review history that is kept.

  • If the user who commits a review is normally different to the user that did the work, then unless Swarm runs as a super user then many changelists will not be cleaned up.

    If the committer created some of the changelists, then those changelists will be removed. However, changelists created by other users will not be removed.

  • If the user has shelved files into changelists without reverting them, then they will still remain in the user's local workspace, and will need to be cleaned up manually.

There is an API endpoint available which can be used by a super user to tidy up changelists which can't be removed automatically. See API Endpoints for details.