From 35f0cfbc9a986529d7ebd5bd411df618f45f8b4e Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 7 Jul 2025 13:07:01 +0200 Subject: [PATCH 1/6] doc updates --- docs/batch-changes/create-a-batch-change.mdx | 170 +++++++++---------- docs/batch-changes/view-batch-changes.mdx | 33 ++++ src/data/navigation.ts | 24 ++- 3 files changed, 129 insertions(+), 98 deletions(-) create mode 100644 docs/batch-changes/view-batch-changes.mdx diff --git a/docs/batch-changes/create-a-batch-change.mdx b/docs/batch-changes/create-a-batch-change.mdx index 5912c3a3e..1fa14915a 100644 --- a/docs/batch-changes/create-a-batch-change.mdx +++ b/docs/batch-changes/create-a-batch-change.mdx @@ -4,14 +4,89 @@ 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`. +There are two ways of creating a batch change: + +1. On your Sourcegraph instance, with [server-side execution](#on-your-sourcegraph-instance) +2. On your local machine, with the [Sourcegraph CLI](#using-the-sourcegraph-cli) + +## On your Sourcegraph instance + +Here, you'll learn how to create and run a batch change via server-side execution. + +To get started, click the **Batch Changes** icon in the top navigation or navigate to `/batch-changes`. + +### Create a batch change + +Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`. + +![create-batch-change-button](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-batch-change-button.png) + +You will be redirected to a page showing you a list of curated templates. + +### Choosing a template + +Templates is a feature available in Sourcegraph 6.6 and later. + +From the template selection page, you can either: + +- **Pick a template** from the list of curated templates that best matches your use case +- **Click "Create batch spec from scratch"** if you prefer to start with a blank spec + +![template-selection](https://sourcegraphstatic.com/docs/images/batch_changes/2024/template-selection.png) + +Your site admin can curate the list of available templates to match your organization's specific needs and use cases. + +### Filling out template fields + +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. + +![template-form-fields](https://sourcegraphstatic.com/docs/images/batch_changes/2024/template-form-fields.png) + +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. If you have suggestions for improving the field descriptions, reach out to your site admin who can update these template fields. + +### Choose a name for your batch change + +After you've filled out the template form fields, or after you clicked "Create batch spec 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. + +![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png) + +Once done, click **Create**. + +### Previewing workspaces + +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. + 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. -There are two ways of creating a batch change: +![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png) + +### Executing your batch spec -1. On your local machine, with the [Sourcegraph CLI](#create-a-batch-change-with-the-sourcegraph-cli) -2. Remotely, with [server-side execution](/batch-changes/server-side) +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: -## Create a batch change with the Sourcegraph CLI +- Run statistics at the top +- All the workspaces, including status and diff stat, in the left panel +- Details on a particular workspace on the right-hand side panel where you can see steps with: + - Logs + - Results + - Command + - Per-step diffs + - Output variables + - Execution timelines for debugging + +Once finished, you can proceed to the batch spec preview, as you know it from before. + +![ssbc_execution_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_execution_screen.png) + +### Previewing and applying the batch spec + +On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**. + +Congratulations, you ran your first batch change server-side 🎊 + +![ssbc_preview_screen](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_preview_screen.png) + +## Using the Sourcegraph CLI This part of the guide will walk you through creating a batch change on your local machine with the Sourcegraph CLI. @@ -83,7 +158,7 @@ src batch preview -f YOUR_BATCH_SPEC.yaml 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. -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). +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). 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). @@ -114,88 +189,3 @@ src batch preview -f your_batch_spec.yaml -namespace Learn how to view, search, and filter your Batch Changes.

+ +## Viewing batch changes + +You can view a list by clicking the **Batch Changes** icon in the top navigation bar: + +![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png) + +### Title-based search + +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. + +Start typing the keywords that match the batch change's title, and you will see a list of relevant results. + +![title-based-search-batch-changes](https://storage.googleapis.com/sourcegraph-assets/Docs/title-based-search-bc.png) + +## Filtering Batch Changes + +You can also use the filters to switch between showing all open or closed Batch Changes. + +![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png) + +## Filtering changesets + +When looking at a batch change, you can search and filter the list of changesets with the controls at the top of the list: + +![filter-changesets](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering_changesets.png) + +## Administration + +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. diff --git a/src/data/navigation.ts b/src/data/navigation.ts index 39759151e..f015e0555 100644 --- a/src/data/navigation.ts +++ b/src/data/navigation.ts @@ -280,19 +280,27 @@ export const navigation: NavigationItem[] = [ href: '/batch-changes/create-a-batch-change', subsections: [ { - title: 'Update a Batch Change', - href: '/batch-changes/update-a-batch-change' + title: 'Sourcegraph UI', + href: '/batch-changes/create-a-batch-change#on-your-sourcegraph-instance' }, { - title: 'Close a Batch Change', - href: '/batch-changes/delete-a-batch-change' - }, - { - title: 'Run Server Side', - href: '/batch-changes/server-side' + title: 'Sourcegraph CLI', + href: '/batch-changes/create-a-batch-change#using-the-sourcegraph-cli' } ] }, + { + title: 'View Batch Changes', + href: '/batch-changes/view-batch-changes' + }, + { + title: 'Update a Batch Change', + href: '/batch-changes/update-a-batch-change' + }, + { + title: 'Close a Batch Change', + href: '/batch-changes/delete-a-batch-change' + }, { title: 'Bulk Operations', href: '/batch-changes/bulk-operations-on-changesets', From 5b94cea2162256fb13b53251be970cf00475d19e Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 7 Jul 2025 13:36:20 +0200 Subject: [PATCH 2/6] update site admin docs --- docs/admin/config/batch_changes.mdx | 32 ++++++++++++++++++-- docs/batch-changes/create-a-batch-change.mdx | 4 ++- 2 files changed, 33 insertions(+), 3 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 92caebee9..3899af960 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -344,9 +344,37 @@ However, if the user deletion is permanent, deleting both account and data, then ## Batch Spec Library - Batch Spec Library is currently in Experimental. +The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. -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. +The library distinguishes between templates and library examples, where library examples are complete batch specs and templates are library examples with placeholders. Both types are managed through the same GraphQL APIs. + +### Library examples + +Library 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, providing reference implementations that can be adapted to specific use cases. + +Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to modify the list of library examples by adding, updating, or removing entries to match your organization's needs. + +As a site admin, you can click the star next to a library record to feature or unfeature that record. Featured records will move to a separate list at the top. + +### Templates + +Templates are supported in Sourcegraph v6.6 and more. + +Parameterized Batch Specs designed 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. + +#### Variables + +Templates use variables to make batch specs adaptable to different scenarios. 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. + +Each variable has the following configuration options: + +- **Name**: The variable identifier used in the template +- **Display name**: Optional human-readable name shown in the form interface +- **Pattern**: Regular expression for input validation +- **Mandatory**: Boolean field indicating whether the variable is required +- **Warning level**: Validation message severity level (`info`, `warning`, or `error`) + +### Managing the Batch Spec Library 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. diff --git a/docs/batch-changes/create-a-batch-change.mdx b/docs/batch-changes/create-a-batch-change.mdx index 1fa14915a..1d5940a80 100644 --- a/docs/batch-changes/create-a-batch-change.mdx +++ b/docs/batch-changes/create-a-batch-change.mdx @@ -52,12 +52,14 @@ After you've filled out the template form fields, or after you clicked "Create b Once done, click **Create**. -### Previewing workspaces +### Previewing batch spec and workspaces 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. 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. +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. + ![ssbc_workspace_preview](https://sourcegraphstatic.com/docs/images/batch_changes/2024/ssbc_workspace_preview.png) ### Executing your batch spec From 2a7bf96a0e60f3e08c649a0b97feac407706a21b Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 7 Jul 2025 13:45:57 +0200 Subject: [PATCH 3/6] wip --- docs/admin/config/batch_changes.mdx | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 3899af960..da6b5adcd 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -346,15 +346,15 @@ However, if the user deletion is permanent, deleting both account and data, then The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. -The library distinguishes between templates and library examples, where library examples are complete batch specs and templates are library examples with placeholders. Both types are managed through the same GraphQL APIs. +The library distinguishes between templates and library examples, where library examples are complete batch specs and templates are library examples with variables. -### Library examples +Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to modify the list of library examples by adding, updating, or removing entries to match your organization's needs. See [Managing the Batch Spec Library](#managing-the-batch-spec-library) for more details. -Library 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, providing reference implementations that can be adapted to specific use cases. +As a site admin, you can [feature records](#featured-records) to highlight the most useful examples for your organization. -Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to modify the list of library examples by adding, updating, or removing entries to match your organization's needs. +### Library examples -As a site admin, you can click the star next to a library record to feature or unfeature that record. Featured records will move to a separate list at the top. +Library 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, providing reference implementations that can be adapted to specific use cases. ### Templates @@ -378,6 +378,8 @@ Each variable has the following configuration options: 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. +Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more. + ```graphql createBatchSpecLibraryRecord(name: "example", spec: "version: 2\nname: example") { id @@ -399,16 +401,12 @@ batchSpecLibrary(first: 100) { } ``` -### Featured Templates - -Featured templates are supported in Sourcegraph v6.4 and more. +### Featured Records -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. +Site-admins can mark a record 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. This will add or remove the `"featured"` [label](#labels). ### Labels -Labels are supported in Sourcegraph v6.4 and more. - Batch Spec Library records support an optional `labels` field for categorization and filtering. Common labels include: - `"featured"` - Marks popular or recommended batch specs that are displayed in a "Featured Templates" section above the remaining examples From d07d4686c13f7b639568da1768ef82ed5fc0601e Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 7 Jul 2025 14:33:12 +0200 Subject: [PATCH 4/6] some cleanup --- docs/admin/config/batch_changes.mdx | 58 +++++++++++++++----- docs/batch-changes/create-a-batch-change.mdx | 6 +- 2 files changed, 47 insertions(+), 17 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index da6b5adcd..15a5c7278 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -346,9 +346,9 @@ However, if the user deletion is permanent, deleting both account and data, then The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. -The library distinguishes between templates and library examples, where library examples are complete batch specs and templates are library examples with variables. +The library distinguishes between [templates](#templates) and [library examples](#library-examples), where library examples are complete batch specs and templates are library examples with variables. -Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to modify the list of library examples by adding, updating, or removing entries to match your organization's needs. See [Managing the Batch Spec Library](#managing-the-batch-spec-library) for more details. +Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library). As a site admin, you can [feature records](#featured-records) to highlight the most useful examples for your organization. @@ -356,29 +356,24 @@ As a site admin, you can [feature records](#featured-records) to highlight the m Library 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, providing reference implementations that can be adapted to specific use cases. +Library 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. + ### Templates Templates are supported in Sourcegraph v6.6 and more. -Parameterized Batch Specs designed 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. - -#### Variables - -Templates use variables to make batch specs adaptable to different scenarios. 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. +Templates are like library 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. -Each variable has the following configuration options: +You can use variables to replace any text in the batch spec, allowing for flexible customization of repository queries, commands, commit messages, and more, but not for the name of the batch change. -- **Name**: The variable identifier used in the template -- **Display name**: Optional human-readable name shown in the form interface -- **Pattern**: Regular expression for input validation -- **Mandatory**: Boolean field indicating whether the variable is required -- **Warning level**: Validation message severity level (`info`, `warning`, or `error`) +A library example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed on the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change). ### Managing the Batch Spec Library +Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more. + 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. -Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more. ```graphql createBatchSpecLibraryRecord(name: "example", spec: "version: 2\nname: example") { @@ -435,3 +430,38 @@ batchSpecLibrary(first: 100, labels: ["featured"]) { } } ``` + +### Variables + +Variables are supported in Sourcegraph v6.6 and more. + +Templates use variables to make batch specs adaptable to different scenarios. 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. + +You cannot use a variable for the batch change or batch spec name. + +The `libraryVariables` field accepts an array of variable objects, each with the following configuration options: + +- **Name**: The variable identifier used in the template +- **Display name**: Optional human-readable name shown in the form interface +- **Pattern**: Regular expression for input validation +- **Description**: Help text shown to users explaining what the variable is for +- **Mandatory**: Boolean field indicating whether the variable is required +- **Level**: Validation message severity level (`INFO`, `WARNING`, or `ERROR`) + +You can create templates by adding the `libraryVariables` field to the `createBatchSpecLibraryRecord` mutation. Here's an example that creates a simple template: + +```graphql +createBatchSpecLibraryRecord(name:"Hello World Template", +libraryVariables: [{ + name:"REPOSITORY_QUERY", + displayName:"Repository Search Query", + pattern: ".+", + description:"The search query to find repositories.", + mandatory:true, + level:ERROR + }], 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") { + id + } +``` + +To update or remove variables from an existing template, you will need to recreate the entire batch spec library record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations. diff --git a/docs/batch-changes/create-a-batch-change.mdx b/docs/batch-changes/create-a-batch-change.mdx index 1d5940a80..8cff6283f 100644 --- a/docs/batch-changes/create-a-batch-change.mdx +++ b/docs/batch-changes/create-a-batch-change.mdx @@ -19,7 +19,7 @@ To get started, click the **Batch Changes** icon in the top navigation or naviga Click the **Create batch change** button on the Batch Changes page, or go to `/batch-changes/create`. -![create-batch-change-button](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-batch-change-button.png) +![create_batch_change_button](https://sourcegraphstatic.com/docs/images/batch_changes/2025/create_batch_change_button.png) You will be redirected to a page showing you a list of curated templates. @@ -32,7 +32,7 @@ From the template selection page, you can either: - **Pick a template** from the list of curated templates that best matches your use case - **Click "Create batch spec from scratch"** if you prefer to start with a blank spec -![template-selection](https://sourcegraphstatic.com/docs/images/batch_changes/2024/template-selection.png) +![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png) Your site admin can curate the list of available templates to match your organization's specific needs and use cases. @@ -40,7 +40,7 @@ Your site admin can curate the list of available templates to match your organiz 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. -![template-form-fields](https://sourcegraphstatic.com/docs/images/batch_changes/2024/template-form-fields.png) +![templates_form](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_form.png) 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. If you have suggestions for improving the field descriptions, reach out to your site admin who can update these template fields. From 5f3010ceb694d3315b676ba76071274d919f9607 Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Mon, 7 Jul 2025 14:42:54 +0200 Subject: [PATCH 5/6] cleanup --- docs/admin/config/batch_changes.mdx | 6 +++--- docs/batch-changes/create-a-batch-change.mdx | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 15a5c7278..17c3c0f93 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -364,10 +364,10 @@ Library examples are visible in the library pane when you are in the batch spec Templates are like library 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. -You can use variables to replace any text in the batch spec, allowing for flexible customization of repository queries, commands, commit messages, and more, but not for the name of the batch change. - A library example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed on the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change). +You can use variables to replace any text in the batch spec, allowing for flexible customization of repository queries, commands, commit messages, and more, but not for the name of the batch change. + ### Managing the Batch Spec Library Site admins can manage the Batch Spec library in Sourcegraph v6.4 and more. @@ -437,7 +437,7 @@ batchSpecLibrary(first: 100, labels: ["featured"]) { Templates use variables to make batch specs adaptable to different scenarios. 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. -You cannot use a variable for the batch change or batch spec name. +You cannot use a variable for the batch change name. The `libraryVariables` field accepts an array of variable objects, each with the following configuration options: diff --git a/docs/batch-changes/create-a-batch-change.mdx b/docs/batch-changes/create-a-batch-change.mdx index 8cff6283f..58998bf04 100644 --- a/docs/batch-changes/create-a-batch-change.mdx +++ b/docs/batch-changes/create-a-batch-change.mdx @@ -30,7 +30,7 @@ You will be redirected to a page showing you a list of curated templates. From the template selection page, you can either: - **Pick a template** from the list of curated templates that best matches your use case -- **Click "Create batch spec from scratch"** if you prefer to start with a blank spec +- **Click "Start from Scratch"** if you prefer to start with a blank spec ![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png) @@ -46,7 +46,7 @@ The form fields are validated by regular expressions. If the validation fails, l ### Choose a name for your batch change -After you've filled out the template form fields, or after you clicked "Create batch spec 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. +After you've filled out the template form fields, or after you 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. ![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png) From 4acbe44645d0e40966ba4072ba6871bf0ed3140e Mon Sep 17 00:00:00 2001 From: Michael Bahr Date: Fri, 11 Jul 2025 09:51:46 +0200 Subject: [PATCH 6/6] review udpates --- docs/admin/config/batch_changes.mdx | 31 ++++++++++---------- docs/batch-changes/create-a-batch-change.mdx | 10 +++---- docs/batch-changes/view-batch-changes.mdx | 6 ++-- 3 files changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx index 17c3c0f93..9779b3cbb 100644 --- a/docs/admin/config/batch_changes.mdx +++ b/docs/admin/config/batch_changes.mdx @@ -344,29 +344,29 @@ However, if the user deletion is permanent, deleting both account and data, then ## Batch Spec Library -The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. +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. -The library distinguishes between [templates](#templates) and [library examples](#library-examples), where library examples are complete batch specs and templates are library examples with variables. +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. -Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library). +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). -As a site admin, you can [feature records](#featured-records) to highlight the most useful examples for your organization. +As a site admin, you can [feature records](#featured-records) to highlight the most useful templates and examples for your organization. -### Library examples +### Examples -Library 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, providing reference implementations that can be adapted to specific use cases. +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. -Library 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. +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. ### Templates Templates are supported in Sourcegraph v6.6 and more. -Templates are like library 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. +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. -A library example becomes a template once it has at least one [variable](#variables) defined. It will then be displayed on the list of templates that a user sees when they click on [create a batch change](/batch-changes/create-a-batch-change). +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). -You can use variables to replace any text in the batch spec, allowing for flexible customization of repository queries, commands, commit messages, and more, but not for the name of the batch change. +Variables can be used to replace any text in the batch spec except the batch change's name. ### Managing the Batch Spec Library @@ -398,14 +398,13 @@ batchSpecLibrary(first: 100) { ### Featured Records -Site-admins can mark a record 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. This will add or remove the `"featured"` [label](#labels). +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. ### Labels -Batch Spec Library records support an optional `labels` field for categorization and filtering. Common labels include: +Library records support an optional `labels` field for categorization and filtering. -- `"featured"` - Marks popular or recommended batch specs that are displayed in a "Featured Templates" section above the remaining examples -- Custom labels for organizational categorization (not exposed to Batch Changes users yet) +The `"featured"` label marks popular or recommended batch specs that are displayed in a featured section above the remaining examples and templates. To remove the featured status, you can update the library record with an empty list of labels (`[]`). @@ -435,7 +434,7 @@ batchSpecLibrary(first: 100, labels: ["featured"]) { Variables are supported in Sourcegraph v6.6 and more. -Templates use variables to make batch specs adaptable to different scenarios. 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. +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. You cannot use a variable for the batch change name. @@ -464,4 +463,4 @@ libraryVariables: [{ } ``` -To update or remove variables from an existing template, you will need to recreate the entire batch spec library record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations. +To update or remove variables from an existing template, you will need to recreate the record using the `deleteBatchSpecLibraryRecord` and `createBatchSpecLibraryRecord` mutations. diff --git a/docs/batch-changes/create-a-batch-change.mdx b/docs/batch-changes/create-a-batch-change.mdx index 58998bf04..751c0147c 100644 --- a/docs/batch-changes/create-a-batch-change.mdx +++ b/docs/batch-changes/create-a-batch-change.mdx @@ -30,7 +30,7 @@ You will be redirected to a page showing you a list of curated templates. From the template selection page, you can either: - **Pick a template** from the list of curated templates that best matches your use case -- **Click "Start from Scratch"** if you prefer to start with a blank spec +- **Click "Start from Scratch"** if you prefer to continue without a template ![templates_list](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_list.png) @@ -42,11 +42,11 @@ If you selected a template, you will need to fill out the form fields specific t ![templates_form](https://sourcegraphstatic.com/docs/images/batch_changes/2025/templates_form.png) -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. If you have suggestions for improving the field descriptions, reach out to your site admin who can update these template fields. +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. ### Choose a name for your batch change -After you've filled out the template form fields, or after you 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. +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. ![server-side-batch-change](https://sourcegraphstatic.com/docs/images/batch_changes/2024/create-a-batch-change.png) @@ -64,7 +64,7 @@ The library contains examples that you can apply right into your batch spec if y ### Executing your batch spec -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: +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: - Run statistics at the top - All the workspaces, including status and diff stat, in the left panel @@ -82,7 +82,7 @@ Once finished, you can proceed to the batch spec preview, as you know it from be ### Previewing and applying the batch spec -On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**. +On this page, you can review the proposed changes. Once satisfied, click **Apply**. Congratulations, you ran your first batch change server-side 🎊 diff --git a/docs/batch-changes/view-batch-changes.mdx b/docs/batch-changes/view-batch-changes.mdx index fb343ae15..9041c5557 100644 --- a/docs/batch-changes/view-batch-changes.mdx +++ b/docs/batch-changes/view-batch-changes.mdx @@ -4,13 +4,13 @@ ## Viewing batch changes -You can view a list by clicking the **Batch Changes** icon in the top navigation bar: +You can view a list of Batch Changes by clicking the **Batch Changes** icon in the top navigation bar: ![batch-change-icon-to-view](https://sourcegraphstatic.com/docs/images/batch_changes/2024/batch_changes_icon_in_menu.png) ### Title-based search -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. +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. Start typing the keywords that match the batch change's title, and you will see a list of relevant results. @@ -18,7 +18,7 @@ Start typing the keywords that match the batch change's title, and you will see ## Filtering Batch Changes -You can also use the filters to switch between showing all open or closed Batch Changes. +You can also use filters to switch between showing all open or closed Batch Changes. ![use-filters-batch-changes](https://sourcegraphstatic.com/docs/images/batch_changes/2024/viewing_batch_changes_filtering.png)