Update campaign docs to include examples and YAML reference (#13638)

* Add examples to campaign docs

This adds back the examples we previously had, adopted to the new
campaign specs.

Where and how the examples are referenced follows what was proposed in
https://github.com/sourcegraph/sourcegraph/pull/10921 but temporarily
removed.

* Add the campaign spec YAML reference

* Add -namespace argument to src commands and fix other things

* Add note about combining tracking/creating changesets

* Fix formatting and "user name" to "username"

* Fix multiline YAML string in campaign spec reference

doc/user/campaigns/campaign_spec_yaml_reference.md

@@ -0,0 +1,225 @@
+# Campaign spec YAML reference
+
+<style>.markdown-body h2 { margin-top: 50px; }</style>
+
+[Sourcegraph campaigns](../index.md) use [campaign specs](../index.md#campaign-specs) to define campaigns.
+
+This page is a reference guide to the campaign spec YAML format in which campaign specs are defined. If you're new to YAML and want a short introduction, see "[Learn YAML in five minutes](https://learnxinyminutes.com/docs/yaml/)."
+
+## [`name`](#name)
+
+The name of the campaign, which is unique among all campaigns in the namespace. A campaign's name is case-preserving.
+
+### Examples
+
+```yaml
+name: update-go-import-statements
+```
+
+```yaml
+name: update-node.js
+```
+
+## [`description`](#description)
+
+The description of the campaign. It's rendered as Markdown.
+
+### Examples
+
+```yaml
+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`
+```
+
+## [`on`](#on)
+
+The set of repositories (and branches) to run the campaign on, specified as a list of search queries (that match repositories) and/or specific repositories.
+
+### Examples
+
+```yaml
+on:
+  - repositoriesMatchingQuery: lang:go fmt.Sprintf("%d", :[v]) patterntype:structural
+  - repository: github.com/sourcegraph/sourcegraph
+```
+
+## [`on.repositoriesMatchingQuery`](#on-repositoriesMatchingQuery)
+
+A Sourcegraph search query that matches a set of repositories (and branches). Each matched repository branch is added to the list of repositories that the campaign will be run on.
+
+See "[Code search](../search/index.md)" for more information on Sourcegraph search queries.
+
+### Examples
+
+```yaml
+on:
+  - repositoriesMatchingQuery: file:README.md -repo:github.com/sourcegraph/src-cli
+```
+
+```yaml
+on:
+  - repositoriesMatchingQuery: lang:typescript file:web const changesetStatsFragment
+```
+
+## [`on.repository`](#on-repository)
+
+A specific repository (and branch) that is added to the list of repositories that the campaign will be run on.
+
+A `branch` attribute specifies the branch on the repository to propose changes to. If unset, the repository's default branch is used.
+
+### Examples
+
+```yaml
+on:
+  - repository: github.com/sourcegraph/src-cli
+```
+
+```yaml
+on:
+  - repository: github.com/sourcegraph/sourcegraph
+    branch: 3.19-beta
+  - repository: github.com/sourcegraph/src-cli
+```
+
+## [`steps`](#steps)
+
+The sequence of commands to run (for each repository branch matched in the `on` property) to produce the campaign's changes.
+
+### Examples
+
+```yaml
+steps:
+  - run: echo "Hello World!" >> README.md
+    container: alpine:3
+```
+
+```yaml
+steps:
+  - run: comby -in-place 'fmt.Sprintf("%d", :[v])' 'strconv.Itoa(:[v])' .go -matcher .go -exclude-dir .,vendor
+    container: comby/comby
+  - run: gofmt -w ./
+    container: golang:1.15-alpine
+```
+
+```yaml
+steps:
+  - run: ./update_dependency.sh
+    container: our-custom-image
+    env:
+      OLD_VERSION: 1.31.7
+      NEW_VERSION: 1.33.0
+```
+
+## [`steps.run`](#steps-run)
+
+The shell command to run in the container. It can also be a multi-line shell script. The working directory is the root directory of the repository checkout.
+
+## [`steps.container`](#steps-run)
+
+The Docker image used to launch the Docker container in which the shell command is run.
+
+The image has to have either the `/bin/sh` or the `/bin/bash` shell.
+
+It is executed using `docker` on the machine on which the [Sourcegraph CLI (`src`)](https://github.com/sourcegraph/src-cli) is executed. If the image exists locally, that is used. Otherwise it's pulled using `docker pull`.
+
+## [`steps.env`](#steps-env)
+
+Environment variables to set in the environment when running this command.
+
+## [`importChangesets`](#importChangesets)
+
+An array describing which already-existing changesets should be imported from the code host into the campaign.
+
+### Examples
+
+```yaml
+importChangesets:
+  - repository: github.com/sourcegraph/sourcegraph
+    externalIDs: [13323, "13343", 13342, 13380]
+  - repository: github.com/sourcegraph/src-cli
+    externalIDs: [260, 271]
+```
+
+## [`importChangesets.repository`](#importChangesets-repository)
+
+The repository name as configured on your Sourcegraph instance.
+
+## [`importChangesets.externalIDs`](#importChangesets-externalIDs)
+
+The changesets to import from the code host. For GitHub this is the pull request number, for GitLab this is the merge request number, for Bitbucket Server this is the pull request number.
+
+## [`changesetTemplate`](#changesetTemplate)
+
+A template describing how to create (and update) changesets with the file changes produced by the command steps.
+
+This defines what the changesets on the code hosts (pull requests on GitHub, merge requests on Gitlab, ...) will look like.
+
+### Examples
+
+```yaml
+changesetTemplate:
+  title: Replace equivalent fmt.Sprintf calls with strconv.Itoa
+  body: This campaign replaces `fmt.Sprintf("%d", integer)` calls with semantically equivalent `strconv.Itoa` calls
+  branch: campaigns/sprintf-to-itoa
+  commit:
+    message: Replacing fmt.Sprintf with strconv.Iota
+  published: false
+```
+
+```yaml
+changesetTemplate:
+  title: Update rxjs in package.json to newest version
+  body: This pull request updates rxjs to the newest version, `6.6.2`.
+  branch: campaigns/update-rxjs
+  commit:
+    message: Update rxjs to 6.6.2
+  published: false
+```
+
+```yaml
+changesetTemplate:
+  title: Run go fmt over all Go files
+  body: Regular `go fmt` run over all our Go files.
+  branch: go-fmt
+  commit:
+    message: Run go fmt
+  published: true
+```
+
+## [`changesetTemplate.title`](#changesetTemplate-title)
+
+The title of the changeset on the code host.
+
+## [`changesetTemplate.body`](#changesetTemplate-body)
+
+The body (description) of the changeset on the code host. If the code supports Markdown you can use it here.
+
+## [`changesetTemplate.branch`](#changesetTemplate-branch)
+
+The name of the Git branch to create or update on each repository with the changes.
+
+## [`changesetTemplate.commit`](#changesetTemplate-commit)
+
+The Git commit to create with the changes.
+
+## [`changesetTemplate.commit.message`](#changesetTemplate-commit-message)
+
+The Git commit message.
+
+## [`changesetTemplate.published`](#changesetTemplate-published)
+
+Whether to publish the changeset.
+
+An unpublished changeset can be previewed on Sourcegraph by any person who can view the campaign, but its commit, branch, and pull request aren't created on the code host.
+
+A published changeset results in a commit, branch, and pull request being created on the code host.

doc/user/campaigns/examples/index.md

@@ -0,0 +1,6 @@
+# Example Campaigns
+
+The following is a list of examples that show how to use [Sourcegraph campaigns](../index.md) to make useful, real-world changes:
+
+- [Refactoring Go code using Comby](refactor_go_comby.md)
+- [Updating Go import statements using Comby](updating_go_import_statements.md)

doc/user/campaigns/examples/refactor_go_comby.md

@@ -0,0 +1,54 @@
+# Refactor Go code using Comby
+
+This campaign rewrites Go statements from
+
+```go
+fmt.Sprintf("%d", number)
+```
+
+to
+
+```go
+strconv.Itoa(number)
+```
+
+since they are equivalent.
+
+Since the replacements could change the formatting of the code, it also runs `gofmt` over the repository.
+
+## Campaign spec
+
+```yaml
+name: sprintf-to-itoa
+description: Run `comby` to replace `fmt.Sprintf("%d", integer)` calls with `strconv.Iota`
+
+# Find all repositories that contain the `fmt.Sprintf` statement using structural search
+on:
+  - repositoriesMatchingQuery: lang:go fmt.Sprintf("%d", :[v]) patterntype:structural
+
+steps:
+  - run: comby -in-place 'fmt.Sprintf("%d", :[v])' 'strconv.Itoa(:[v])' .go -matcher .go -exclude-dir .,vendor
+    container: comby/comby
+  - run: gofmt -w ./
+    container: golang:1.15-alpine
+
+# Describe the changeset (e.g., GitHub pull request) you want for each repository.
+changesetTemplate:
+  title: Replace equivalent fmt.Sprintf calls with strconv.Itoa
+  body: This campaign replaces `fmt.Sprintf("%d", integer)` calls with semantically equivalent `strconv.Itoa` calls
+  branch: campaigns/sprintf-to-itoa # Push the commit to this branch.
+  commit:
+    message: Replacing fmt.Sprintf with strconv.Iota
+  published: false
+```
+
+## Instructions
+
+1. Save the campaign spec above as `YOUR_CAMPAIGN_SPEC.campaign.yaml`.
+1. Create a campaign from the campaign spec by running the following [Sourcegraph CLI (`src`)](https://github.com/sourcegraph/src-cli) command:
+
+    <pre><code>src campaign preview -f <em>YOUR_CAMPAIGN_SPEC.campaign.yaml</em> -namespace USERNAME_OR_ORG</code></pre>
+
+1. Open the preview URL that the command printed out.
+1. Examine the preview. Confirm that the changesets are the ones you intended to track. If not, edit the campaign spec and then rerun the command above.
+1. Click the **Create campaign** button.

doc/user/campaigns/examples/updating_go_import_statements.md

@@ -0,0 +1,60 @@
+# Updating Go import statements using Comby
+
+This campaign rewrites Go import paths for the `log15` package from `gopkg.in/inconshreveable/log15.v2` to `github.com/inconshreveable/log15` using [Comby](https://comby.dev/).
+
+It can handle single-package import statements like these
+
+```go
+import "gopkg.in/inconshreveable/log15.v2"
+```
+
+and multi-package import statements like these:
+
+```go
+import (
+	"io"
+
+	"github.com/pkg/errors"
+	"gopkg.in/inconshreveable/log15.v2"
+)
+```
+
+## Campaign spec
+
+```yaml
+name: update-log15-import
+description: This campaign updates Go import paths for the `log15` package from `gopkg.in/inconshreveable/log15.v2` to `github.com/inconshreveable/log15` using [Comby](https://comby.dev/)
+
+# Find all repositories that contain the import we want to change.
+on:
+  - repositoriesMatchingQuery: lang:go gopkg.in/inconshreveable/log15.v2
+
+# In each repository
+steps:
+  # we first replace the import when it's part of a multi-package import statement
+  - run: comby -in-place 'import (:[before]"gopkg.in/inconshreveable/log15.v2":[after])' 'import (:[before]"github.com/inconshreveable/log15":[after])' .go -matcher .go -exclude-dir .,vendor
+    container: comby/comby
+  # ... and when it's a single import line.
+  - run: comby -in-place 'import "gopkg.in/inconshreveable/log15.v2"' 'import "github.com/inconshreveable/log15"' .go -matcher .go -exclude-dir .,vendor
+    container: comby/comby
+
+# Describe the changeset (e.g., GitHub pull request) you want for each repository.
+changesetTemplate:
+  title: Update import path for log15 package to use GitHub
+  body: Updates Go import paths for the `log15` package from `gopkg.in/inconshreveable/log15.v2` to `github.com/inconshreveable/log15` using [Comby](https://comby.dev/)
+  branch: campaigns/update-log15-import # Push the commit to this branch.
+  commit:
+    message: Fix import path for log15 package
+  published: false
+```
+
+## Instructions
+
+1. Save the campaign spec above as `YOUR_CAMPAIGN_SPEC.campaign.yaml`.
+1. Create a campaign from the campaign spec by running the following [Sourcegraph CLI (`src`)](https://github.com/sourcegraph/src-cli) command:
+
+    <pre><code>src campaign preview -f <em>YOUR_CAMPAIGN_SPEC.campaign.yaml</em> -namespace USERNAME_OR_ORG</code></pre>
+
+1. Open the preview URL that the command printed out.
+1. Examine the preview. Confirm that the changesets are the ones you intended to track. If not, edit the campaign spec and then rerun the command above.
+1. Click the **Create campaign** button.

doc/user/campaigns/hello_world_campaign.md

@@ -62,7 +62,9 @@ Let's see the changes that will be made. Don't worry---no commits, branches, or
 
 1. In your terminal, run this command:
 
-    <pre><code>src campaign preview -f hello-world.campaign.yaml</code></pre>
+    <pre><code>src campaign preview -f hello-world.campaign.yaml -namespace <em>USERNAME_OR_ORG</em></code></pre>
+
+    > The `namespace` can be your Sourcegraph username or the name of a Sourcegraph organisation under which you want to create the campaign.
 1. Wait for it to run and compute the changes for each repository.
 1. When it's done, click the displayed link to see all of the changes that will be made.
 1. Make sure the changes look right.
@@ -76,12 +78,14 @@ You created your first campaign! The campaign's changesets are still unpublished
 
 Publishing causes commits, branches, and changesets to be created on your code host.
 
-You probably don't want to publish these toy "Hello World" changesets to actively developed repositories, because that might confuse people ("Why did you add this line to our READMEs?"). On a real campaign, you would click the **Publish** button next to a changeset to publish it (or the **Publish all** button to publish all changesets).
+You probably don't want to publish these toy "Hello World" changesets to actively developed repositories, because that might confuse people ("Why did you add this line to our READMEs?").
+
+On a real campaign, you would change the `published: false` in the `hello-world.campaign.yaml` to `published: true` and run the `src campaign preview` command again.
 
 ## Congratulations!
 
 You've created your first campaign! 🎉🎉
 
-You can customize your campaign spec and experiment with making other types of changes. To update your campaign, edit `hello-world.campaign.yaml` and run `src campaign preview -f hello-world.campaign.yaml` again. (As before, you'll see a preview before any changes are applied.)
+You can customize your campaign spec and experiment with making other types of changes. To update your campaign, edit `hello-world.campaign.yaml` and run `src campaign preview` again. (As before, you'll see a preview before any changes are applied.)
 
 To learn what else you can do with campaigns, see "[Campaigns](index.md)" in Sourcegraph documentation.