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.

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></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></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/index.md

@@ -41,10 +41,16 @@ If you lack read access to a repository in a campaign, you can only see [limited
 
 ### Campaign specs
 
-You can create or update a campaign from a campaign spec, which is a YAML file that defines a campaign.
+You can create or update a campaign from a campaign spec, which is a YAML file that defines a campaign. You then use the [Sourcegraph CLI (`src`)](https://github.com/sourcegraph/src-cli) to apply the campaign spec.
 
 See the [Creating a campaign](#creating-a-campaign) section for an example campaign spec YAML file.
 
+For more information, see:
+
+- [Creating a campaign](#creating-a-campaign)
+- [Updating a campaign](#creating-a-campaign)
+- [Example campaign specs](examples.md)
+
 <!-- - TODO(sqs) <u>Campaign spec YAML reference</u> -->
 
 ## Creating a campaign
@@ -97,6 +103,13 @@ If a person viewing the campaign lacks read access to a repository in the campai
 
 You can update a campaign's changes at any time, even after you've published changesets. For more information, see [Updating a campaign](#updating-a-campaign).
 
+### Example campaigns
+
+The [example campaigns](examples/index.md) show how to use campaigns to make useful, real-world changes:
+
+- [Refactoring Go code using Comby](examples/refactor_go_comby.md)
+- [Updating Go import statements using Comby](examples/updating_go_import_statements.md)
+
 ## Publishing changesets to the code host
 
 After you've added patches, you can see a preview of the changesets (e.g., GitHub pull requests) that will be created from the patches. Publishing the changesets will, for each repository:
@@ -145,12 +158,11 @@ If you lack read access to a repository, you can only see [limited information a
 
 ## Updating a campaign
 
-<!-- TODO(sqs): needs wireframes/mocks -->
-
 You can edit a campaign's name, description, and any other part of its campaign spec at any time.
 
 To update a campaign, you need [admin access to the campaign](managing_access.md#campaign-access-for-each-permission-level), and [write access to all affected repositories](managing_access.md#repository-permissions-for-campaigns) with published changesets.
 
+1. Update the [campaign spec](#campaign-specs) to include the changes you want to make to the campaign. For example, change the `description` of the campaign or change the commit message in the `changesetTemplate`.
 1. In your terminal, run the [Sourcegraph CLI (`src`)](https://github.com/sourcegraph/src-cli) command shown. The command will execute your campaign spec to generate changes and then upload them to the campaign for you to preview and accept.
 
     <pre><code>src campaign preview -f <em>YOUR_CAMPAIGN_SPEC.campaign.yaml</em></code></pre>
@@ -201,10 +213,10 @@ Any person with [admin access to the campaign](managing_access.md#permission-lev
 1. Click the <img src="campaigns-icon.svg" alt="Campaigns icon" /> campaigns icon in the top navigation bar.
 1. In the list of campaigns, click the campaign that you'd like to close or delete.
 1. In the top right, click the **Close** button.
-1. Select whether you want to close all of the campaign's changesets (e.g., closing all associated GitHub pull requests on the code host).
+1. Select whether you want to close all of the campaign's open changesets (e.g., closing all associated GitHub pull requests on the code host).
 1. Click **Close campaign**.
 
-## [Managing access to campaigns]
+## Managing access to campaigns
 
 See [Managing access to campaigns](managing_access.md).
 
@@ -238,9 +250,9 @@ To learn about the internals of campaigns, see [Campaigns](../../dev/campaigns_d
 
 ### Known issues
 
-<!-- TODO(sqs): This section is rough/incomplete/outline-only. -->
-
 - Campaigns currently support **GitHub**, **GitLab** and **Bitbucket Server** repositories. If you're interested in using campaigns on other code hosts, [let us know](https://about.sourcegraph.com/contact).
 - It is not yet possible for a campaign to create multiple changesets in a single repository (e.g., to make changes to multiple subtrees in a monorepo).
 - Forking a repository and creating a pull request on the fork is not yet supported. Because of this limitation, you need write access to each repository that your campaign will change (in order to push a branch to it).
 - Campaign steps are run locally (in the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli)). Sourcegraph does not yet support executing campaign steps (which can be arbitrary commands) on the server. For this reason, the APIs for creating and updating a campaign require you to upload all of the changeset specs (which are produced by executing the campaign spec locally). {#server-execution}
+- It is not yet possible for multiple users to edit the same campaign that was created under an organization.
+- It is currently not yet possible to reuse a branch in a repository across multiple campaigns.