Models

There are two code review models: pre-commit and post-commit. Which model you use for code reviews with Swarm is up to you.

Pre-commit model

The pre-commit model is possible due to Helix Core Server's shelving feature. Shelving enables you to temporarily make copies of your files available to other users without committing the changes into the depot. Shelving can be a very handy way for developers to create a backup, or to handle local workspace changes that might otherwise lose work in progress, without having to commit code that might destabilize a codebase.

Swarm uses the shelving feature in Helix Core Server to manage code reviews. Shelving allows reviewers to easily acquire a copy of the code to be reviewed, and allows updates to the reviewed code prior to submission.

For more information on shelving, see Shelve Changelists in Helix Core Command-Line (P4) Guide.

Post-commit model

The post-commit model can be used if your team's development processes preclude the use of shelving. Code must be committed to the Helix Core Server before code review can begin, which reduces the opportunity to fix problems before, for example, a continuous integration system notices problems. However, code reviews can be started for any existing code regardless of how long it has been committed.

Internal representation

Swarm-managed changelists

A code review consists of one or more shelved changelists that Swarm manages. A shelved changelist is a pending changelist that has a snapshot of its files on a shelf associated with the changelist.

When a review is started, Swarm creates a new changelist that becomes the review changelist. What happens afterwards varies:

• If the review contains uncommitted work (the pre-commit model), Swarm copies the shelved files from the user's changelist that initiated the review into the review's changelist.
• Any time that a user's changelist associated with the review has its shelved files updated, Swarm copies the shelved files into its review changelist and creates an archive changelist. An archive changelist is no different from any other pending changelist with shelved files, but it allows Swarm to provide versioning and diffs within a review.
• If the head version of a review is committed (the post-commit model), the review's changelist is emptied of files.

The review's changelist is never actually committed; this allows the review to be opened later with additional shelved changes.

$ p4 changelists -u swarm
Change 1212285 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructions'
Change 1212284 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructions'
...

Swarm-managed workspaces

Whenever Swarm creates a changelist for a review, it uses a client workspace (or just workspace) associated with the configured Helix Core Server userid that has admin privileges. Whenever a user commits a change via Swarm's user interface, Swarm uses a workspace associated with that user.

To learn more about workspaces, see Helix Core Server as a version control implementation in the Solutions Overview: Helix Core Version Control System Guide.

The workspaces that Swarm creates and uses live in the SWARM_ROOT/data/clients folder.

Inside the clients folder, Swarm maintains a user-specific folder that contains any workspace folders that may be required. Each user-specific folder is named by converting their Helix Core Server userid into hexadecimal to avoid any characters that would be problematic in the filesystem, such as slashes, accents, UTF-8 characters, etc. For example, the folder for the user steve.russell would be named 73746576652e72757373656c6c.

Within the user-specific folder are the folders that become the root of each workspace. Each of these folders is named with a globally-unique identifier (GUID) prefixed with swarm-, for example swarm-438d482b-f107-9a35-c06c-86ac68136b00. Accompanying each folder is a lock file with the same name plus the .lock extension. Finally, the user-specific clients folder contains a management lock file called manage.lock.

Here is an example of the folder structure:

SWARM_ROOT/
	data/
		clients/
		  73746576652e72757373656c6c/
			manage.lock
			swarm-438d482b-f107-9a35-c06c-86ac68136b00/
			swarm-438d482b-f107-9a35-c06c-86ac68136b00.lock
			swarm-8388362a-233d-0cb9-3e90-895eaaa99f6c/
			swarm-8388362a-233d-0cb9-3e90-895eaaa99f6c.lock
		  7061756c612e626f796c65/
			manage.lock
			swarm-da7de4b4-0ecb-12c8-1b35-f3e32bb18033/
			swarm-da7de4b4-0ecb-12c8-1b35-f3e32bb18033.lock

Here are the steps Swarm takes when it needs to use a client:

1. Convert the current connection's userid to hexadecimal.
2. Check to see whether a user-specific folder exists within SWARM_ROOT/data/clients; if not, create the folder.

3. Within the user-specific folder, loop over any existing workspace folders and attempt to lock each in turn:

   If a lock is acquired skip to the next step. Otherwise, perform the following procedure.

   Create workspace procedure:

   1. Check if the max number of clients for the current user has been reached:

      • If so, wait a short amount of time (50 milliseconds), and start step 3 again.
      • If not, proceed to the next step.
   2. Take a lock on manage.lock.

   3. Check if the max number of clients for the current user has been reached:

      • If so, release the manage.lock, wait a short amount of time (50 milliseconds), and start step 3 again.
      • If not, proceed to the next step.
   4. Create a new workspace folder using a GUID-based filename, and take a lock on the folder.
   5. Release the manage.lock lock.
4. Perform the necessary file operations using the locked workspace folder.

5. Revert the file content within the workspace folder to avoid having constantly growing disk space use.

   Note

   There may occasionally be stray files left; Swarm is not aggressive about cleaning up.

6. Swarm releases the lock on the workspace folder.

Most users should only require 1-2 workspaces, and those are only required if they commit from Swarm. The admin user that Swarm is configured to use should only use one workspace per configured worker.

By default, the number of workspaces that could be active at any given instant is two times the number of configured workers. Since the default worker count is three, Swarm would use at most six workspaces simultaneously.

If the workspace limit is reached, further file processing is blocked until a workspace becomes available. Potentially, this means that users could encounter timeouts. Configuring Swarm to use more workers could solve that issue.

Removal considerations

Administrators might wish to remove Swarm-managed workspaces. There are a few considerations that should be assessed prior to removal:

• Ideally, you should stop the web server (taking Swarm out of service) before removing a Swarm-managed workspace from the Swarm server; this eliminates the risk of removing a workspace that is in use.

  If you do not stop the web server first, Swarm may encounter an error during a submit.

• Removal of a Swarm-managed workspace folder does not remove the client spec from the Helix Core Server. Unless the client spec is removed, that workspace effectively becomes orphaned. Orphaned clients are, of themselves, not a big concern as the storage and performance impact is negligible.

• Removal of a Swarm-managed workspace's corresponding client spec in the Helix Core Server can be done. However, you should never remove a client spec that has associated shelved files.

  Usually, the only client specs that should have associated shelved files belong to the admin account that Swarm is configured to use. All other workspaces that may exist for other users are primarily used for submitting changes, and so should not have shelved files associated.