Skip to content

Commit 353b920

Browse files
bahrmichaelbahrmichael
authored
feat: docs for batch spec library and templates (#1244)
This PR updates the documentation for the batch spec library following the introduction of batch spec templates. Most notably it - gives an explanation of library examples vs templates for admins, along with a new section on how to use variables, - restructures the page about creating a batch change to show server side batch changes on the top with info about templates, and moves the info on how to use the src-cli to the bottom, - moves info on viewing batch changes into a dedicated page. For easier reviewing of the new content, I created two PDFs: [Batch Changes site admin configuration reference - Sourcegraph docs.pdf](https://github.com/user-attachments/files/21102883/Batch.Changes.site.admin.configuration.reference.-.Sourcegraph.docs.pdf) [Creating a Batch Change - Sourcegraph docs.pdf](https://github.com/user-attachments/files/21102885/Creating.a.Batch.Change.-.Sourcegraph.docs.pdf) ## Pull Request approval You will need to get your PR approved by at least one member of the Sourcegraph team. For reviews of docs formatting, styles, and component usage, please tag the docs team via the #docs Slack channel.
1 parent 9b9b343 commit 353b920

File tree

4 files changed

+197
-109
lines changed

4 files changed

+197
-109
lines changed

‎docs/admin/config/batch_changes.mdx‎

Lines changed: 66 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -344,12 +344,37 @@ However, if the user deletion is permanent, deleting both account and data, then
344344

345345
## Batch Spec Library
346346

347-
<Callout type="note"> Batch Spec Library is currently in Experimental.</Callout>
347+
The Batch Spec Library offers curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. As a site admin you can manage the library.
348348

349-
The Batch Spec Library is a collection of Batch Specs that can be used to create Batch Changes. Sourcegraph provides a few Batch Specs out of the box.
349+
The library distinguishes between [templates](#templates) and [examples](#library-examples). Examples are batch specs that are meant to be modified by power users who are comfortable with the batch spec syntax. Templates, on the other hand, are batch specs that contain variables that the user can provide data for through form fields without having to modify the batch spec code.
350+
351+
Sourcegraph instances come with a couple of examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library).
352+
353+
As a site admin, you can [feature records](#featured-records) to highlight the most useful templates and examples for your organization.
354+
355+
### Examples
356+
357+
Examples are complete batch specs intended for advanced users who are comfortable working with YAML and writing code. These examples serve as inspiration and starting points for custom batch changes.
358+
359+
Examples are visible in the library pane when you are in the batch spec editor. They are not displayed by default in the templates list which is the entry point for users creating a batch change. See [choosing a template](/batch-changes/create-a-batch-change#choosing-a-template) for more details.
360+
361+
### Templates
362+
363+
<Callout type="note">Templates are supported in Sourcegraph v6.6 and more.</Callout>
364+
365+
Templates are like examples, but with variables for easy reuse across multiple batch changes. Templates provide the simplest path for users to create batch changes without needing to learn Batch Spec YAML syntax. Users select from a curated list of templates and complete a form with the required parameters, making batch change creation accessible to all team members regardless of their technical background.
366+
367+
An example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed in the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change).
368+
369+
Variables can be used to replace any text in the batch spec except the batch change's name.
370+
371+
### Managing the Batch Spec Library
372+
373+
<Callout type="note">Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more.</Callout>
350374

351375
Site admins can manage the library through the GraphQL mutations `createBatchSpecLibraryRecord`, `updateBatchSpecLibraryRecord`, and `deleteBatchSpecLibraryRecord`. Use the query `batchSpecLibrary` to list all available Batch Spec examples.
352376

377+
353378
```graphql
354379
createBatchSpecLibraryRecord(name: "example", spec: "version: 2\nname: example") {
355380
id
@@ -371,20 +396,15 @@ batchSpecLibrary(first: 100) {
371396
}
372397
```
373398

374-
### Featured Templates
375-
376-
<Callout type="note">Featured templates are supported in Sourcegraph v6.4 and more.</Callout>
399+
### Featured Records
377400

378-
Site-admins can mark a template as featured by either clicking the star button next to the list of library records. Featured records will automatically move to a section atop the remaining library records.
401+
Site-admins can mark a record as featured by either clicking the star button next to the list of library records or adding the `"featured"` [label](#labels) label with a GraphQL mutation. Featured records will automatically move to a section atop the remaining library records.
379402

380403
### Labels
381404

382-
<Callout type="note">Labels are supported in Sourcegraph v6.4 and more.</Callout>
405+
Library records support an optional `labels` field for categorization and filtering.
383406

384-
Batch Spec Library records support an optional `labels` field for categorization and filtering. Common labels include:
385-
386-
- `"featured"` - Marks popular or recommended batch specs that are displayed in a "Featured Templates" section above the remaining examples
387-
- Custom labels for organizational categorization (not exposed to Batch Changes users yet)
407+
The `"featured"` label marks popular or recommended batch specs that are displayed in a featured section above the remaining examples and templates.
388408

389409
To remove the featured status, you can update the library record with an empty list of labels (`[]`).
390410

@@ -409,3 +429,38 @@ batchSpecLibrary(first: 100, labels: ["featured"]) {
409429
}
410430
}
411431
```
432+
433+
### Variables
434+
435+
<Callout type="note">Variables are supported in Sourcegraph v6.6 and more.</Callout>
436+
437+
When creating a template, you can define placeholders for values that will vary between different uses of the template. Users filling out the template see these variables as form fields where they can enter specific values like repository names, file paths, or commit messages.
438+
439+
<Callout type="note">You cannot use a variable for the batch change name.</Callout>
440+
441+
The `libraryVariables` field accepts an array of variable objects, each with the following configuration options:
442+
443+
- **Name**: The variable identifier used in the template
444+
- **Display name**: Optional human-readable name shown in the form interface
445+
- **Pattern**: Regular expression for input validation
446+
- **Description**: Help text shown to users explaining what the variable is for
447+
- **Mandatory**: Boolean field indicating whether the variable is required
448+
- **Level**: Validation message severity level (`INFO`, `WARNING`, or `ERROR`)
449+
450+
You can create templates by adding the `libraryVariables` field to the `createBatchSpecLibraryRecord` mutation. Here's an example that creates a simple template:
451+
452+
```graphql
453+
createBatchSpecLibraryRecord(name:"Hello World Template",
454+
libraryVariables: [{
455+
name:"REPOSITORY_QUERY",
456+
displayName:"Repository Search Query",
457+
pattern: ".+",
458+
description:"The search query to find repositories.",
459+
mandatory:true,
460+
level:ERROR
461+
}], spec: "version: 2\nname: hello-world\ndescription: Add Hello World to READMEs\n\non:\n - repositoriesMatchingQuery: $REPOSITORY_QUERY\n\nsteps:\n - run: echo Hello World | tee -a README.md\n container: alpine:3\n\nchangesetTemplate:\n title: Hello World\n body: Add Hello World to README\n branch: hello-world\n commit:\n message: Add Hello World to README") {
462+
id
463+
}
464+
```
465+
466+
To update or remove variables from an existing template, you will need to recreate the record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations.

‎docs/batch-changes/create-a-batch-change.mdx‎

Lines changed: 82 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,91 @@
44

55
Batch Changes are created by writing a [batch spec](/batch-changes/batch-spec-yaml-reference) and executing that batch spec with the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli) `src`.
66

7+
There are two ways of creating a batch change:
8+
9+
1. On your Sourcegraph instance, with [server-side execution](#on-your-sourcegraph-instance)
10+
2. On your local machine, with the [Sourcegraph CLI](#using-the-sourcegraph-cli)
11+
12+
## On your Sourcegraph instance
13+
14+
Here, you'll learn how to create and run a batch change via server-side execution.
15+
16+
To get started, click the **Batch Changes** icon in the top navigation or navigate to `/batch-changes`.
17+
18+
### Create a batch change
19+
20+
Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.
21+
22+
![create_batch_change_button](https://sourcegraphstatic.com/docs/images/batch_changes/2025/create_batch_change_button.png)
23+
24+
You will be redirected to a page showing you a list of curated templates.
25+
26+
### Choosing a template
27+
28+
<Callout type="info">Templates is a feature available in Sourcegraph 6.6 and later.</Callout>
29+
30+
From the template selection page, you can either:
31+
32+
- **Pick a template** from the list of curated templates that best matches your use case
33+
- **Click "Start from Scratch"** if you prefer to continue without a template
34+
35+
![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png)
36+
37+
Your site admin can curate the list of available templates to match your organization's specific needs and use cases.
38+
39+
### Filling out template fields
40+
41+
If you selected a template, you will need to fill out the form fields specific to that template. These fields will customize the batch spec to your specific requirements.
42+
43+
![templates_form](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_form.png)
44+
45+
The form fields are validated by regular expressions. If the validation fails, look at the description of that field to see what kind of value is required.
46+
47+
### Choose a name for your batch change
48+
49+
After you've filled out the template form fields, or after you've clicked "Start from Scratch", you will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.
50+
51+
![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)
52+
53+
Once done, click **Create**.
54+
55+
### Previewing batch spec and workspaces
56+
57+
You can now see the batch spec and run a preview of the affected repositories and workspaces from the right-hand side panel. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.
58+
759
Batch Changes can also be used on [multiple projects within a monorepo](/batch-changes/creating-changesets-per-project-in-monorepos) by using the `workspaces` key in your batch spec.
860

9-
There are two ways of creating a batch change:
61+
The library contains examples that you can apply right into your batch spec if you need inspiration. Your site admin can manage the library of examples.
62+
63+
![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)
64+
65+
### Executing your batch spec
66+
67+
When the spec is ready to run, ensure the [preview](/batch-changes/create-a-batch-change#previewing-workspaces) is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:
68+
69+
- Run statistics at the top
70+
- All the workspaces, including status and diff stat, in the left panel
71+
- Details on a particular workspace on the right-hand side panel where you can see steps with:
72+
- Logs
73+
- Results
74+
- Command
75+
- Per-step diffs
76+
- Output variables
77+
- Execution timelines for debugging
78+
79+
Once finished, you can proceed to the batch spec preview, as you know it from before.
80+
81+
![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)
1082

11-
1. On your local machine, with the [Sourcegraph CLI](#create-a-batch-change-with-the-sourcegraph-cli)
12-
2. Remotely, with [server-side execution](/batch-changes/server-side)
83+
### Previewing and applying the batch spec
84+
85+
On this page, you can review the proposed changes. Once satisfied, click **Apply**.
1386

14-
## Create a batch change with the Sourcegraph CLI
87+
Congratulations, you ran your first batch change server-side 🎊
88+
89+
![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)
90+
91+
## Using the Sourcegraph CLI
1592

1693
This part of the guide will walk you through creating a batch change on your local machine with the Sourcegraph CLI.
1794

@@ -83,7 +160,7 @@ src batch preview -f YOUR_BATCH_SPEC.yaml
83160

84161
After you've applied a batch spec, you can [publish changesets](/batch-changes/publishing-changesets) to the code host when you're ready. This will turn the patches into commits, branches, and changesets (such as GitHub pull requests) for others to review and merge.
85162

86-
You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/create-a-batch-change#viewing-batch-changes).
163+
You can share the link to your batch change with other users if you want their help. Any user on your Sourcegraph instance can [view it in the batch changes list](/batch-changes/view-batch-changes).
87164

88165
If a user viewing the batch change lacks read access to a repository in the batch change, they can only see [limited information about the changes to that repository](/batch-changes/permissions-in-batch-changes#repository-permissions-for-batch-changes) (and not the repository name, file paths, or diff).
89166

@@ -114,88 +191,3 @@ src batch preview -f your_batch_spec.yaml -namespace <SOURCEGRAPH_USERNAME_OR_OR
114191
```
115192

116193
When creating a batch change server-side using the UI, you can select the namespace to which the batch change belongs when you create it.
117-
118-
### Administration
119-
120-
Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.
121-
122-
## Create a batch change with server-side execution
123-
124-
Here, you'll learn how to create and run a batch change via server-side execution.
125-
126-
Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`.
127-
You will be prompted to choose a name for your namespace and optionally define a custom namespace to put your batch change in.
128-
129-
![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png)
130-
131-
Once done, click **Create**.
132-
133-
### Editing the spec file
134-
135-
You should see the editor view now. This view consists of three main areas:
136-
137-
- The library sidebar panel on the left
138-
- The editor in the middle
139-
- The workspaces preview panel on the right
140-
141-
![ssbc_editor_panels](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_editor_panels.png)
142-
143-
You can pick from the examples in the library pane to get started quickly or begin working on your batch spec in the editor right away. Site admins can configure the examples. The editor will provide documentation as you hover over tokens in the YAML spec and supports auto-completion.
144-
145-
### Previewing workspaces
146-
147-
Once satisfied or to test your batch change's scope, you can run a new preview from the right-hand side panel at any time. After resolution, it will show all the workspaces in repositories that match the given `on` statements. You can search through them and determine if your query is satisfying before starting execution. You can also exclude single workspaces from this list.
148-
149-
![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png)
150-
151-
### Executing your batch spec
152-
153-
When the spec is ready to run, ensure the preview is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see:
154-
155-
- Run statistics at the top
156-
- All the workspaces, including status and diff stat, in the left panel
157-
- Details on a particular workspace on the right-hand side panel where you can see steps with:
158-
- Logs
159-
- Results
160-
- Command
161-
- Per-step diffs
162-
- Output variables
163-
- Execution timelines for debugging
164-
165-
Once finished, you can proceed to the batch spec preview, as you know it from before.
166-
167-
![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png)
168-
169-
### Previewing and applying the batch spec
170-
171-
On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**.
172-
173-
Congratulations, you ran your first batch change server-side 🎊
174-
175-
![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png)
176-
177-
## Viewing batch changes
178-
179-
You can view a list by clicking the **Batch Changes** icon in the top navigation bar:
180-
181-
![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png)
182-
183-
### Title-based search
184-
185-
You can search through your previously created batch changes by title. This search experience makes it much easier to find the batch change you’re looking for, especially when you have large volumes of batch changes to monitor.
186-
187-
Start typing the keywords that match the batch change’s title, and you will see a list of relevant results.
188-
189-
![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png)
190-
191-
## Filtering Batch Changes
192-
193-
You can also use the filters to switch between showing all open or closed Batch Changes.
194-
195-
![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)
196-
197-
## Filtering changesets
198-
199-
When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:
200-
201-
![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)

‎docs/batch-changes/view-batch-changes.mdx‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Viewing Batch Changes
2+
3+
<p className="subtitle">Learn how to view, search, and filter your Batch Changes.</p>
4+
5+
## Viewing batch changes
6+
7+
You can view a list of Batch Changes by clicking the **Batch Changes** icon in the top navigation bar:
8+
9+
![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png)
10+
11+
### Title-based search
12+
13+
You can search through your previously created batch changes by title. This search experience makes it easier to find the batch change you're looking for, especially when you have large volumes of batch changes to monitor.
14+
15+
Start typing the keywords that match the batch change's title, and you will see a list of relevant results.
16+
17+
![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png)
18+
19+
## Filtering Batch Changes
20+
21+
You can also use filters to switch between showing all open or closed Batch Changes.
22+
23+
![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)
24+
25+
## Filtering changesets
26+
27+
When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list:
28+
29+
![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png)
30+
31+
## Administration
32+
33+
Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who can administer it, such as editing or deleting it. When a batch change is created in a user namespace, only that user (and site admins) can administer it. When a batch change is created in an organization namespace, all members of that organization (and site admins) can administer it.

‎src/data/navigation.ts‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -275,19 +275,27 @@ export const navigation: NavigationItem[] = [
275275
href: '/batch-changes/create-a-batch-change',
276276
subsections: [
277277
{
278-
title: 'Update a Batch Change',
279-
href: '/batch-changes/update-a-batch-change'
278+
title: 'Sourcegraph UI',
279+
href: '/batch-changes/create-a-batch-change#on-your-sourcegraph-instance'
280280
},
281281
{
282-
title: 'Close a Batch Change',
283-
href: '/batch-changes/delete-a-batch-change'
284-
},
285-
{
286-
title: 'Run Server Side',
287-
href: '/batch-changes/server-side'
282+
title: 'Sourcegraph CLI',
283+
href: '/batch-changes/create-a-batch-change#using-the-sourcegraph-cli'
288284
}
289285
]
290286
},
287+
{
288+
title: 'View Batch Changes',
289+
href: '/batch-changes/view-batch-changes'
290+
},
291+
{
292+
title: 'Update a Batch Change',
293+
href: '/batch-changes/update-a-batch-change'
294+
},
295+
{
296+
title: 'Close a Batch Change',
297+
href: '/batch-changes/delete-a-batch-change'
298+
},
291299
{
292300
title: 'Bulk Operations',
293301
href: '/batch-changes/bulk-operations-on-changesets',

0 commit comments

Comments
 (0)