Add transformChanges to campaign spec and document it (#16235)

* Extend CampaignSpec schema with transformChanges

* Change branchSuffix to branch

* Add transformChanges to campaign spec YAML ref

* Update campaign spec schema to newest state

* Update doc/campaigns/references/campaign_spec_yaml_reference.md

Co-authored-by: Chris Pine <chrispine@sourcegraph.com>

* Add changelog entry

Co-authored-by: Chris Pine <chrispine@sourcegraph.com>

CHANGELOG.md

@@ -24,6 +24,7 @@ All notable changes to Sourcegraph are documented in this file.
 - The campaigns preview page is much more detailed now, especially when updating existing campaigns. [#16240](https://github.com/sourcegraph/sourcegraph/pull/16240)
 - When a newer version of a campaign spec is uploaded, a message is now displayed when viewing the campaign or an outdated campaign spec. [#14532](https://github.com/sourcegraph/sourcegraph/issues/14532)
 - Changesets in a campaign can now be searched by title and repository name. [#15781](https://github.com/sourcegraph/sourcegraph/issues/15781)
+- Experimental: [`transformChanges` in campaign specs](https://docs.sourcegraph.com/campaigns/references/campaign_spec_yaml_reference#transformchanges) is now available as a feature preview to allow users to create multiple changesets in a single repository. [#16235](https://github.com/sourcegraph/sourcegraph/pull/16235)
 
 ### Changed
 

doc/campaigns/references/campaign_spec_yaml_reference.md

@@ -1,6 +1,18 @@
 # Campaign spec YAML reference
 
-<style>.markdown-body h2 { margin-top: 50px; }</style>
+<style>
+.markdown-body h2 { margin-top: 50px; }
+
+/* The sidebar on this page contains a lot of long identifiers without
+whitespace. In order to make them more readable we increase the width of the
+sidebar. /*
+@media (min-width: 1200px) {
+  body > #page > main > #index {
+    width: 35%;
+  }
+}
+
+</style>
 
 [Sourcegraph campaigns](../index.md) use [campaign specs](../explanations/introduction_to_campaigns.md#campaign-spec) to define campaigns.
 
@@ -33,11 +45,11 @@ description: This campaign changes all `fmt.Sprintf` calls to `strconv.Iota`.
 ```yaml
 description: |
   This campaign changes all imports from
-  
+
   `gopkg.in/sourcegraph/sourcegraph-in-x86-asm`
-  
+
   to
-  
+
   `github.com/sourcegraph/sourcegraph-in-x86-asm`
 ```
 
@@ -455,3 +467,63 @@ changesetTemplate:
     - "*": true
     - github.com/*: draft
 ```
+
+
+## [`transformChanges`](#transformchanges)
+
+<aside class="experimental">
+<span class="badge badge-experimental">Experimental</span> <code>transformChanges</code> is an experimental feature in Sourcegraph 3.23 and <a href="https://github.com/sourcegraph/src-cli">Sourcegraph CLI</a> 3.23. It's a <b>preview</b> of functionality we're currently exploring to make managing large changes in large repositories easier. If you have any feedback, please let us know!
+</aside>
+
+A description of how to transform the changes (diffs) produced in each repository before turning them into separate changeset specs by inserting them into the [`changesetTemplate`](#changesettemplate).
+
+This allows the creation of multiple changeset specs (and thus changesets) in a single repository.
+
+### Examples
+
+```yaml
+# Transform the changes produced in each repository.
+transformChanges:
+  # Group the file diffs by directory and produce an additional changeset per group.
+  group:
+    # Create a separate changeset for all changes in the top-level `go` directory
+    - directory: go
+      branch: my-campaign-go # will replace the `branch` in the `changesetTemplate`
+
+    - directory: internal/codeintel
+      branch: my-campaign-codeintel # will replace the `branch` in the `changesetTemplate`
+      repository: github.com/sourcegraph/src-cli # optional: only apply the rule in this repository
+```
+
+
+```yaml
+transformChanges:
+  group:
+    - directory: go/utils/time
+      branch: my-campaign-go-time
+
+    # The *last* matching directory is used, not the most specific one,
+    # so only this changeset would be opened.
+    - directory: go/utils
+      branch: my-campaign-go-date
+```
+
+## [`transformChanges.group`](#transformchanges-group)
+
+A list of groups to define which file diffs to group together to create an additional changeset in the given repository.
+
+The **order of the list matters**, since each file diff's filepath is matched against the `directory` of a group and the **last match** is used.
+
+## [`transformChanges.group.directory`](#transformchanges-group-directory)
+
+The name of the directory in which file diffs should be grouped together.
+
+## [`transformChanges.group.branch`](#transformchanges-group-branch)
+
+The branch that should be used for this additional changeset. This **overwrites the [`changesetTemplate.branch`](#changesettemplate-branch)** when creating the additional changeset.
+
+**Important**: the branch can _not_ be nested under the [`changesetTemplate.branch`](#changesettemplate-branch), i.e. if the `changesetTemplate.branch` is `my-campaign` then this can _not_ be `my-campaign/my-subdirectory` since [git doesn't allow that](https://stackoverflow.com/a/22630664).
+
+## [`transformChanges.group.repository`](#transformchanges-repository)
+
+Optional: the file diffs matching the given directory will only be grouped in a repository with that name configured on your Sourcegraph instance.

schema/campaign_spec.schema.json

@@ -115,6 +115,36 @@
         }
       }
     },
+    "transformChanges": {
+      "type": "object",
+      "description": "Optional transformations to apply to the changes produced in each repository.",
+      "additionalProperties": false,
+      "properties": {
+        "group": {
+          "type": "array",
+          "description": "A list of groups of changes in a repository that each create a separate, additional changeset for this repository, with all ungrouped changes being in the default changeset.",
+          "additionalProperties": false,
+          "required": ["directory", "branchSuffix"],
+          "properties": {
+            "directory": {
+              "type": "string",
+              "description": "The directory path (relative to the repository root) of the changes to include in this group.",
+              "minLength": 1
+            },
+            "branch": {
+              "type": "string",
+              "description": "The branch on the repository to propose changes to. If unset, the repository's default branch is used.",
+              "minLength": 1
+            },
+            "repository": {
+              "type": "string",
+              "description": "Only apply this transformation in the repository with this name (as it is known to Sourcegraph).",
+              "examples": ["github.com/foo/bar"]
+            }
+          }
+        }
+      }
+    },
     "importChangesets": {
       "type": "array",
       "description": "Import existing changesets on code hosts.",