Review cleanup

This section describes the configurables that can be set for review cleanup.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

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 Core Server 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 committing user. In the case where a user is committing 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 committing user, you can do this by granting the Helix Core Server 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 user permissions using an external script. This removes the need for the Swarm Helix Core Server user to have super privileges. See Pending review cleanup example for details.

  • 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 set to true, changelists will always be cleaned up.

    If set to false, changelists 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.