Creating multiple changesets in large repositories

Overview

Batch changes can produce a lot of changes in a single repository. In order to make reviewing and merging the changes easier, it can be helpful to split the changes up into multiple changesets.

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

Using transformChanges

The following batch 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 batch change!
  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 batch 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 a unique branch for each directory 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 batch spec YAML reference on transformChanges for more details.