Add a changelist to a review

Once a review has been started you can add a changelist to the review. It can be useful to add changelists to an existing review. For example, if follow up changes are made to files in a review or if you need to group a number of changelists under a single review.

By default, for a pre-commit or a post-commit review, when a changelist is updated, all of the files in the review are replaced with the files in the changelist you are adding to the review. See Replace review with a pending changelist.

The Add change option in the Review actions Image of the Review actions button button is used to add a changelist to an existing review. The option is not available if the review is in a state that is protected from change by the review workflow rules. For details of the On update of a review in an end state rule, see Workflow rules.

Tip

You can also add a changelist to a review directly from the changelist description. See Review creation and modification outside of Swarm.

The options available for the Add change option depend on whether the review is pre-commit or post-commit:

  • Pre-commit reviews:
    • Append pending changelist: when you add a pending changelist to a review, the files in the changelist are appended to the existing files in the review. See Append a pending changelist to a review.

      • Note

      A review can only contain 1 stream spec. If you append a changelist with a stream spec to a review that already contains a stream spec, the spec in the changelist replaces the original one in the review. If it is a different spec from the original spec in the review, Swarm cannot display the diff between them and displays File content unchanged.

    • Replace with pending changelist: when you add a pending changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review. See Replace review with a pending changelist.
    • Replace with committed changelist: when you add a committed changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review. See Replace review with a committed changelist.
      • Note

      If you replace a pre-commit review with a committed changelist, the new version of the review will be a post-commit review.

  • Post-commit reviews:
    • Replace with pending changelist: when you add a pending changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review. See Replace review with a pending changelist.
      • Note

      If you replace a post-commit review with a pending changelist, the new version of the review will be a pre-commit review.

    • Replace with committed changelist: when you add a committed changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review. See Replace review with a committed changelist.
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.

Append a pending changelist to a review

The Append pending changelist option is used to add a pending changelist to a pre-commit review.

Example:

  • Original review contains the following files: A#1, B#2, C#1, D#1, and E#4
  • Changelist contains the following files: A#2, C#3, E#4 (marked for delete), and F#1
  • Appending the changelist to the original review generates a new version of the review that contains the following files: A#2, B#2, C#3, D#1, E#4 (marked for delete), and F#1
Important

Committing a review with Swarm (recommended): Swarm automatically commits the files in the approved version of the review.

Committing a review outside of Swarm:

Before you commit the review:

  1. Unshelve the review into the pending changelist associated with the review.
  2. Reshelve the files in the pending changelist.
  3. Commit the pending changelist.
  4. This process ensures that all of the files in the approved version of the review are committed.

    5. Workflow feature enabled (default):

    Swarm can be configured to automatically check that the files being committed match the files in the approved version of the review by using the On commit with a review workflow rule. For information about the On commit with a review rule, see Workflow rules.

    Workflow feature disabled:

    Swarm can be configured to automatically check that the files being committed match the files in the approved version of the review by using the strict trigger option.

To append a changelist to a review:

  1. Click the Review actions Image of the Review actions button button.
  2. Select Append pending changelist from the dropdown menu and the append review dialog is displayed with a list of recent pending changelists.
  3. Enter the pending changelist number directly in the @ Change box, filter by depot path and user, or select a changelist from the list of recent changelists.
    4. Note

    The changelist must not be part of another review, if it is Swarm will reject it.

  4. Click Select to append the changelist to the review.
  5. The changelist is appended to the review and the review version is updated.

Replace review with a pending changelist

The Replace with a pending changelist option is used to replace the files in a review with the files in a pending changelist.

Note

If you replace a post-commit review with a pending changelist, the new version of the review will be a pre-commit review.

Example:

  • Original review contains the following files: A#1, B#2, C#1, D#1, and E#4
  • Changelist contains the following files: A#2, C#3, E#4 (marked for delete), and F#1
  • Replacing the original review with the changelist generates a new version of the review that contains the following files: A#2, C#3, E#4 (marked for delete), and F#1
Tip

When you replace a review with a changelist, the base revisions of the files in the new version of the review are the base revisions of the files in the replacement changelist.

To replace the files in a review with the files in a changelist:

  1. Click the Review actions Image of the Review actions button button.
  2. Select Replace with a pending changelistfrom the dropdown menu and the replace review dialog is displayed with a list of recent pending changelists:
  3. Enter the pending changelist number directly in the @ Change box, filter by depot path and user, or select a changelist from the list of recent changelists.
    4. Note

    The changelist must not be part of another review, if it is Swarm will reject it.

  4. Click Select to replace the review with the changelist.
  5. The changelist files replace the files in the review and the review version is updated.

Replace review with a committed changelist

The Replace with a committed changelist option is used to replace the files in a review with the files in a committed changelist.

Note

If you replace a pre-commit review with a committed changelist, the new version of the review will be a post-commit review.

Example:

  • Original review contains the following files: A#1, B#2, C#1, D#1, and E#4
  • Changelist contains the following files: A#2, C#3, E#4 (marked for delete), and F#1
  • Replacing the original review with the changelist generates a new version of the review that contains the following files: A#2, C#3, E#4 (marked for delete), and F#1
Tip

When you replace a review with a changelist, the base revisions of the files in the new version of the review are the base revisions of the files in the replacement changelist.

To replace the files in a review with the files in a changelist:

  1. Click the Review actions Image of the Review actions button button.
  2. Select Replace with a committed changelist from the dropdown menu and the replace review dialog is displayed with a list of recent committed changelists:
  3. Enter the committed changelist number directly in the @ Change box, filter by depot path and user, or select a changelist from the list of recent changelists.
    4. Note

    The changelist must not be part of another review, if it is Swarm will reject it.

  4. Click Select to replace the review with the changelist.
  5. The changelist files replace the files in the review and the review version is updated.