Review workflow

There are many possible code review workflows. The section describes typical scenarios for a code review that Swarm can handle.

Basic review workflow

This section describes a basic workflow when reviewing code with Swarm.

Another developer reviews your code

  1. You request a code review with a shelved change.
  2. Another developer, Bill, sees the email notification from Swarm, clicks the review link in the email, and begins looking at the diffs in the files belonging to the review. Curious about an implementation detail, Bill clicks the line he's curious about and adds his query in a Swarm comment.
  3. You receive an email notification regarding Bill's query. His query prompts you to clarify the code, say by renaming some variables and adding some better descriptive text in the surrounding code comments. You then update the review with your changes.
  4. Bill sees the email notification that you have updated the review. He checks out the change, likes what he sees, and marks the review Approved.
  5. You see the email notification that Bill has approved your review, so you commit your code.

You review the code from another developer

  1. Another developer, Charlie, requests a code review with a shelved change.
  2. You receive an email notification from Swarm, click the review link in the email, and begin looking at the diffs in the files in the review. You don't like what you see, as Charlie has tried to fix a bug using a technique you have already tried previously and know to be incorrect. You add comments to the code that needs attention, flag your comments as tasks, and mark the review Needs revision.
  3. Charlie receives an email notification regarding your review, but disagrees with you, and adds his own comments justifying his implementation.
  4. You receive an email notification regarding Charlie's comment. The technique is somewhat complicated, so rather than attempt to describe how it is incorrect, you unshelve the review's code to your own workspace, change Charlie's code, and shelve your changes. Swarm updates the review with your new code.
  5. Charlie receives an email notification regarding your updates to the review. He's still unconvinced, but he unshelves your changes to try them in his local workspace. He finds that your implementation works better, but sees a couple of areas where there could be improvements. He reshelves his latest work to update the review.
  6. You receive an email notification regarding Charlie's updates, check out his changes, and realize that Charlie's work is now moot because the customer has revised his plans. You add a comment to the review reporting that fact, and Reject the review.

Additional workflow tasks

This section describes additional workflow tasks that can be used with the basic workflow described above.

Remove a file from a review

Important

Swarm must be configured to use this function, see Process shelf file delete when.

When configured, Swarm will automatically remove files from a review when they have been deleted from an associated shelved changelist and the review is in a specified state. Typically Swarm is configured to remove files from a review when the review state is Needs review and Needs revision but not when it is any other state.

To remove a file from a review using P4V:

  1. Right-click the shelved file you want to remove from the review.
  2. Select Delete, and click Yes when prompted to confirm the deletion. The file is removed from the associated review if the review is in one of the states specified in the Swarm configuration.
Tip

If you want to tidy up your workspace by deleting an unused shelf without removing the files from an associated review, see Deleting shelves.

Revert the content of a review to match an earlier review version

If the content of the latest version of a review contains changes you want to rollback, or is created by mistake, you can revert the review content to match an earlier version of the review. This section describes the process for reverting the content of a review.

Tip
  • Reverting the content of a review increments the review version, it does not change the review version to the version you are reverting to.
  • It is good practice to update the review description, or add a comment, so that users know that you have reverted the review with files from an earlier version.

To revert the content of a review:

  1. Find the changelist number for the review version you want to revert to.
    2. Tip

    The changelist numbers in a review can be found using the review version selector on the review page, see Select review versions to view.

  2. Unshelve the changes from the changelist you found in the previous step.
  3. Create a new changelist and shelve the changes into the new changelist.
  4. Use Swarm to navigate to the review you want to revert.
  5. Select the Add change option, and select Replace with pending changelist from the dropdown list. The Select a pending changelist to replace the review dialog is displayed.
  6. Select the new changelist you shelved the files in and click Select. The new changelist files replace the files in the review and the review version is updated.

Fix a review if it has been replaced with the wrong changelist

If you or another user has replaced the files in your review with the wrong changelist, you can fix the mistake so that the review contains the correct files.

For example:

  1. Create a pending changelist with files A#1, and B#1, this is changelist 250.
  2. Request a review of changelist 250 using Swarm by clicking the Request Review button on the changelist page.
    • Version 1 of review 251 is created containing files A#1, and B#1.
  3. Go to review 251 in Swarm, select the Add change option, select Replace with committed changelist, and select changelist 241. Changelist 241 contains files X#1, and Y#1.
    • This replaces the files in the review with the files in changelist 241.
    • Version 2 of review 251 is created, containing only files X#1, and Y#1.
  4. You realize that you have made a mistake, you meant to append changelist 242 to review 251.

Fix the mistake:

Review-251 should contain files A#1, and B#1from changelist 250 and files C#1, and D#1 from changelist 242.

Tip

It is good practice to update the review description, or add a comment, so that users know why you have changed the files in the review.

  1. Go to review 251 in Swarm, select the Add change option, select Replace with pending changelist, and select changelist 242. Changelist 242 contains files C#1, and D#1.
    • This replaces the files in the review with the files in changelist 242.
    • Version 3 of review 251 is created, containing files C#1, and D#1.
  2. Edit the description of changelist 250 to change #review-251 to #append-251, this changes the add mode for review-251 to append.
  3. Shelve your files in pending changelist 250. Changelist 250 contains files A#1, and B#1. This appends the files to the review because that is the default add mode for review-251.
    • Version 4 of review 251 is created, containing files A#1, B#1, C#1, and D#1.

Review creation and modification outside of Swarm

You can create a review and add a changelist to a review from outside of Swarm by adding keywords to the changelist description. The keyword is processed by Swarm when the changelist is shelved for review, when files in a pending changelist that is associated with a review are reshelved, and when a changelist is committed. For details on using a keyword to create a review and add a changelist to a review, see Create a review and Add a changelist to a review.

Note

Swarm acts on the first valid keyword it finds in the changelist description, Swarm then ignores any further valid keywords it finds in the description.

Tip

When the content of a review is changed, Swarm checks to see which branches are in the new version of the review:

  • If a new branch was added to the review:
    • Default reviewers on the new branch are added to the review.
    • Moderators from the added branch become moderators for the review alongside the existing moderators.
    • Only if workflow is enabled: if the new branch is associated with a workflow, the workflow is merged with the existing workflow. The most restrictive workflow is used for the review.
  • If a branch is no longer part of the review:
    • Reviewers for the review are not changed.
    • Moderators from the removed branch no longer moderate the review.
    • Only if workflow is enabled: if the branch was associated with a workflow, the branch workflow is removed from the review.

The following examples show how adding keywords to the changelist descriptions works in practice. In each case, you are collaborating with other users to produce a single review in Swarm:

Basic workflow using #review and #append in the changelist description

  1. You create a review with files A#1, B#1, and C#1 by using #review in the changelist description.
  2. Review-xxxx is created and #review is automatically replaced with #review-xxxx in the changelist description.
  3. User-2 appends their changelist that contains files C#2, D#1, and E#1 to review-xxxx by using #append-xxxx in the changelist description.
    • Review-xxxx now contains files A#1, B#1, C#2, D#1, and E#1.
    • The default add mode for review-xxxx is now append because User-2 added the changelist to the review using #append-xxxx.
  4. You edit files A#1 and B#1 in your changelist so they become A#2 and B#2. The changelist description still contains #review-xxxx.
  5. You shelve your pending changelist which has #review-xxxx in the changelist description, this appends the files to the review because that is the default add mode for review-xxxx.
    • Review-xxxx now contains files A#2, B#2, C#2, D#1, and E#1.

Advanced workflow using #review and #append in the changelist description

  1. You create a review with files A#1 and B#1 by using #review in the changelist description.
  2. Review-xxxx is created and #review is automatically replaced with #review-xxxx in the changelist description.
  3. User-2 appends their changelist that contains file C#1 to review-xxxx by using #append-xxxx in the changelist description.
    • Review-xxxx now contains files A#1, B#1, C#1.
    • The default add mode for review-xxxx is now append because User-2 added the changelist to the review using #append-xxxx.
  4. User-3 adds their changelist that contains files A#2 and D#1 to review-xxxx by using #review-xxxx in the changelist description. This appends the files to the review because that is the default add mode for review-xxxx.
    • Review-xxxx now contains files A#2, B#1, C#1, and D#1.
  5. You edit files A#2 and B#1 in your changelist so they become A#3 and B#2, and you add file E#1. The changelist description still contains #review-xxxx.
  6. You shelve your pending changelist which has #review-xxxx in the changelist description, this appends the files to the review because that is the default add mode for review-xxxx.
    • Review-xxxx now contains files A#3, B#2, C#1, D#1, and E#1.

Advanced workflow using #review, #append, and #replace in the changelist description

  1. You create a review with files A#1 and B#1 by using #review in the changelist description.
  2. Review-xxxx is created and #review is automatically replaced with #review-xxxx in the changelist description.
  3. User-2 appends their changelist that contains file C#1 to review-xxxx by using #append-xxxx in the changelist description.
    • Review-xxxx now contains files A#1, B#1, C#1.
    • The default add mode for review-xxxx is now append because User-2 added the changelist to the review using #append-xxxx.
  4. User-3 replaces review-xxxx with their changelist that contains files A#2 and D#1 to review-xxxx by using #replace-xxxx in the changelist description.
    • Review-xxxx now contains files A#2 and D#1.
    • The default add mode for review-xxxx is now replace because User-3 added the changelist to the review using #replace-xxxx.
  5. You edit files A#2 and B#1 in your changelist so they become A#3 and B#2, and you add file E#1. The changelist description still contains #review-xxxx.
  6. You shelve your pending changelist which has #review-xxxx in the changelist description, this replaces the files in the review because that is the default add mode for review-xxxx.
    • Review-xxxx now contains files A#3, B#2, and E#1.