Creating multiple changesets in large repositories

Overview

Campaigns can produce a lot of changes in a single repository and in order to make reviewing and merging them easier, it might make sense to split the changes up into multiple changesets.

That can be done by using transformChanges in the campaign spec to group the changes produced in one single repository by directory and create a changeset for each group.

Using transformChanges

The following campaign spec uses the transformChanges property to create up to 4 changesets in a single repository by grouping the changes made in different directories:

name: hello-world
description: Add Hello World to READMEs

# Find all repositories that contain a README.md file.
on:
  - repositoriesMatchingQuery: file:README.md

# In each repository, run this command. Each repository's resulting diff is captured.
steps:
  - run: echo Hello World | tee -a $(find -name README.md)
    container: alpine:3

# Transform the changes produced in each repository.
transformChanges:
  # Group the file diffs by directory and produce one additional changeset per group.
  # Changes that haven't been grouped will be be in the standard changeset.
  group:
    - directory: client
      branch: hello-world-client # will replace the `branch` in the `changesetTemplate`
    - directory: docker-images
      # Optional: only apply the rule in this repository
      repository: github.com/sourcegraph/sourcegraph
      branch: hello-world-infra
    - directory: monitoring
      repository: github.com/sourcegraph/sourcegraph
      branch: hello-world-monitoring

# Describe the changeset (e.g., GitHub pull request) you want for each repository.
changesetTemplate:
  title: Hello World
  body: My first campaign!
  branch: hello-world # This branch is the default branch and will be
                      # overwritten for each additional changeset.
  commit:
    message: Append Hello World to all README.md files
  published: false # Do not publish any changes to the code hosts yet

This campaign spec will produce up to 4 changesets in the github.com/sourcegraph/sourcegraph repository:

1. a changeset with the changes in the client directory
2. a changeset with the changes in docker-images
3. a changeset with the changes in monitoring
4. a changeset with the changes in the other directories.

Since code hosts and git don't allow creating multiple, different changesets on the same branch, it is required to specify the branch that will be used for the additional changesets. That branch will overwrite the default branch specified in changesetTemplate.

In case no changes have been made in a directory specified in a group, no additional changeset will be produced.

If the optional repository property is specified only the changes in that repository will be grouped.

See the campaign spec YAML reference on transformChanges for more details.