Batch Changes Revamp (#281)

This PR revamps the complete section of our Batch Changes docs. Ships a new IA for the left nav. --------- Co-authored-by: Bolaji Olajide <[email protected]>
sourcegraph · Jun 13, 2024 · 5e64db1 · 5e64db1
1 parent 6a643d0
commit 5e64db1
Show file tree

Hide file tree

Showing 94 changed files with 6,541 additions and 2,565 deletions.
diff --git a/docs/CHANGELOG.mdx b/docs/CHANGELOG.mdx
@@ -303,7 +303,7 @@ feature.feat(appliance): deploy codeinsights-dbReady for review, but draft until
 - [62702](https://github.com/sourcegraph/sourcegraph/pull/62702) sg: add repo annotation to delivery pipeline
 - [62703](https://github.com/sourcegraph/sourcegraph/pull/62703) sg: clarify `repository` annotation meaning in delivery pipeline
 - [62705](https://github.com/sourcegraph/sourcegraph/pull/62705) gitserver: Allow multiple ranges to be passed to Commits
-- [62706](https://github.com/sourcegraph/sourcegraph/pull/62706) feat/enterprise-portal: DB layer for \{Get/List\}CodyGatewayAccess 
+- [62706](https://github.com/sourcegraph/sourcegraph/pull/62706) feat/enterprise-portal: DB layer for \{Get/List\}CodyGatewayAccess
 - [62709](https://github.com/sourcegraph/sourcegraph/pull/62709) gitserver: Use git-diff-tree to simplify validation and improve security
 - [62710](https://github.com/sourcegraph/sourcegraph/pull/62710) observability: Fix error checks in ErrorsFilter
 - [62711](https://github.com/sourcegraph/sourcegraph/pull/62711) inference: Fix regression for non-absolute commit ID
@@ -338,7 +338,7 @@ feature.feat(appliance): deploy codeinsights-dbReady for review, but draft until
 - [62763](https://github.com/sourcegraph/sourcegraph/pull/62763) Fix a condition I negated by accident
 - [62764](https://github.com/sourcegraph/sourcegraph/pull/62764) fix(sg/eph): handle nil regex
 - [62769](https://github.com/sourcegraph/sourcegraph/pull/62769) bazel: Cleanup oci_deps.bzl
-- [62771](https://github.com/sourcegraph/sourcegraph/pull/62771) feat/enterprise-portal: ConnectRPC layer for \{Get/List\}CodyGatewayAccess 
+- [62771](https://github.com/sourcegraph/sourcegraph/pull/62771) feat/enterprise-portal: ConnectRPC layer for \{Get/List\}CodyGatewayAccess
 - [62773](https://github.com/sourcegraph/sourcegraph/pull/62773) gitserver: Deprecate Exec and remove localGit
 - [62775](https://github.com/sourcegraph/sourcegraph/pull/62775) gitserver: Switch corruption logs to use separate file
 - [62776](https://github.com/sourcegraph/sourcegraph/pull/62776) gitserver: Made git GC recloning less dependent on time
@@ -1044,7 +1044,7 @@ The following PRs were merged onto the previous release branch but could not be
   issue when `log.AuditLogs.SeverityLevel` was set below the overall instance log level. `log.AuditLogs.SeverityLevel` has
   been marked as deprecated and will be removed in a future release [#52566](https://github.com/sourcegraph/sourcegraph/pull/52566)
 - Update minimum supported Redis version to 6.2 [#52248](https://github.com/sourcegraph/sourcegraph/pull/52248)
-- The batch spec properties [`transformChanges`](/batch_changes/references/batch_spec_yaml_reference#transformchanges) and [`workspaces`](/batch_changes/references/batch_spec_yaml_reference#workspaces) are now generally available.
+- The batch spec properties [`transformChanges`](/batch-changes/batch-spec-yaml-reference#transformchanges) and [`workspaces`](/batch-changes/batch-spec-yaml-reference#workspaces) are now generally available.
 - Cody feature flags have been simplified [#52919](https://github.com/sourcegraph/sourcegraph/pull/52919) See [the docs page for complete setup details](/cody/explanations/enabling_cody_enterprise)
   - `cody.enabled` in site-config now controls whether Cody is on/off, default `false`.
   - When `cody.enabled` is set and no specific configuration for `completions` and `embeddings` are given, Cody will by default talk to the `sourcegraph` provider, Sourcegraphs Cody Gateway which allows access to chat completions and embeddings.

diff --git a/docs/admin/access_control/batch_changes.mdx b/docs/admin/access_control/batch_changes.mdx
@@ -1,6 +1,6 @@
 # Access control for Batch Changes
 
-Granular controls for who can access [Batch Changes](/batch_changes/) can be configured by site admins by tuning the roles assigned to users and the permissions granted to those roles. This page describes the permission types available for Batch Changes, and whether they are granted by default to the **User** [system role](/admin/access_control#system-roles). All permissions are granted to the **Site Administrator** system role by default.
+Granular controls for who can access [Batch Changes](/batch-changes/) can be configured by site admins by tuning the roles assigned to users and the permissions granted to those roles. This page describes the permission types available for Batch Changes, and whether they are granted by default to the **User** [system role](/admin/access_control#system-roles). All permissions are granted to the **Site Administrator** system role by default.
 
         Name          |                                                                                                                    Description                                                                                                                     | Granted to **User** by default?
 --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----------------------------:

diff --git a/docs/admin/code_hosts/bitbucket_server.mdx b/docs/admin/code_hosts/bitbucket_server.mdx
@@ -15,7 +15,7 @@ Also consider installing the [Sourcegraph Bitbucket Server plugin](/integration/
 
 Sourcegraph requires a Bitbucket Server / Bitbucket Data Center personal access token with **read** permissions to sync repositories.
 
-When using [batch changes](/batch_changes/) the access token needs **write** permissions on the project and repository level. See "[Code host interactions in batch changes](/batch_changes/explanations/permissions_in_batch_changes#code-host-interactions-in-batch-changes)" for details.
+When using [batch changes](/batch-changes/) the access token needs **write** permissions on the project and repository level. See "[Code host interactions in batch changes](/batch-changes/permissions-in-batch-changes#code-host-interactions-in-batch-changes)" for details.
 
 You can create a personal access token at `https://[your-bitbucket-hostname]/plugins/servlet/access-tokens/add`. Also set the corresponding `username` field.
 

diff --git a/docs/admin/code_hosts/github.mdx b/docs/admin/code_hosts/github.mdx
@@ -62,7 +62,7 @@ To create a GitHub App and connect it to Sourcegraph:
 
 9. (Optional) If you want to sync repositories from other organization or user namespaces and your GitHub App is set to public visibility, you can create additional installations with **Add installation**.
 
-> NOTE: If you are using [Batch Changes](/batch_changes/), you can create a GitHub App to perform [commit signing](/admin/config/batch_changes#commit-signing-for-github) (Beta).
+> NOTE: If you are using [Batch Changes](/batch-changes/), you can create a GitHub App to perform [commit signing](/admin/config/batch_changes#commit-signing-for-github) (Beta).
 
 ### Multiple installations
 
@@ -188,7 +188,7 @@ No [token scopes](https://docs.github.com/en/developers/apps/building-oauth-apps
 
 [permissions]: #repository-permissions
 [permissions-caching]: #teams-and-organizations-permissions-caching
-[batch-changes]: /batch_changes/
+[batch-changes]: /batch-changes/
 [batch-changes-interactions]: /batch_changes/explanations/permissions_in_batch_changes#code-host-interactions-in-batch-changes
 
 

diff --git a/docs/admin/code_hosts/gitlab.mdx b/docs/admin/code_hosts/gitlab.mdx
@@ -340,7 +340,7 @@ We are actively collaborating with GitLab to improve our integration (e.g. the [
 | [`GET /users/:id`](https://docs.gitlab.com/ee/api/users.html#single-user) | `read_user`, `api` or `read_api` | If using GitLab OAuth, used to fetch user metadata during the OAuth sign in process. |
 | [`GET /projects/:id`](https://docs.gitlab.com/ee/api/projects.html#get-single-project) | `api` or `read_api` | (1) If using GitLab OAuth and repository permissions, used to determine if a user has access to a given _project_; (2) Used to query repository metadata (e.g. description) for display on Sourcegraph. |
 | [`GET /projects/:id/repository/tree`](https://docs.gitlab.com/ee/api/repositories.html#list-repository-tree) | `api` or `read_api` | If using GitLab OAuth and repository permissions, used to verify a given user has access to the file contents of a repository within a project (i.e. does not merely have `Guest` permissions). |
-| Batch Changes requests | `api` or `read_api`, `read_repository`, `write_repository` | [Batch Changes](/batch_changes/) require write access to push commits and create, update and close merge requests on GitLab repositories. See "[Code host interactions in batch changes](/batch_changes/explanations/permissions_in_batch_changes#code-host-interactions-in-batch-changes)" for details. |
+| Batch Changes requests | `api` or `read_api`, `read_repository`, `write_repository` | [Batch Changes](/batch-changes/) require write access to push commits and create, update and close merge requests on GitLab repositories. See "[Code host interactions in batch changes](/batch-changes/permissions-in-batch-changes#code-host-interactions-in-batch-changes)" for details. |
 
 ## Webhooks
 

diff --git a/docs/admin/config/batch_changes.mdx b/docs/admin/config/batch_changes.mdx
@@ -50,7 +50,7 @@ Keep in mind that if you configure a rollout window that is too aggressive, you
 * [GitLab](https://docs.gitlab.com/ee/user/gitlab_com/.html#gitlabcom-specific-rate-limits)
 * [Bitbucket Cloud](https://support.atlassian.com/bitbucket-cloud/docs/api-request-limits/)
 
-When using a [global service account token](/batch_changes/how-tos/configuring_credentials#global-service-account-tokens) with Batch Changes, keep in mind that this token will also be used for other Batch Changes with code host interactions, too.
+When using a [global service account token](/batch-changes/configuring-credentials#global-service-account-tokens) with Batch Changes, keep in mind that this token will also be used for other Batch Changes with code host interactions, too.
 
 You may encounter this error when publishing changesets to GitHub:
 
@@ -141,9 +141,9 @@ Sourcegraph can track incoming webhooks from code hosts to more easily debug iss
 
 <Callout type="note"> Feature supported only in Sourcegraph versions 3.36 or more.</Callout>
 
-Sourcegraph can be configured to push branches created by Batch Changes to a fork of the repository, rather than the repository itself, for example if users of your code host typically do not have push access to the original repository. You can enable pushing to forks globally with the `batchChanges.enforceForks` site configuration option. Users can also indicate they do or do not want to push to forks for an individual batch change by specifying the property `changesetTemplate.fork` in their batch spec. If the batch spec property is present, it will override the site configuration option. See the [batch spec YAML reference](/batch_changes/references/batch_spec_yaml_reference#changesettemplate-fork) for more information.
+Sourcegraph can be configured to push branches created by Batch Changes to a fork of the repository, rather than the repository itself, for example if users of your code host typically do not have push access to the original repository. You can enable pushing to forks globally with the `batchChanges.enforceForks` site configuration option. Users can also indicate they do or do not want to push to forks for an individual batch change by specifying the property `changesetTemplate.fork` in their batch spec. If the batch spec property is present, it will override the site configuration option. See the [batch spec YAML reference](/batch-changes/batch-spec-yaml-reference#changesettemplatefork) for more information.
 
-The fork will be created in the namespace of the user publishing the changeset, or the namespace of the service account if [global service account](/batch_changes/how-tos/configuring_credentials#global-service-account-tokens) is in use. The name of the fork Sourcegraph creates will be prefixed with the name of the original repo's namespace in order to prevent potential repo name collisions. For example, a batch spec targeting `github.com/my-org/project` would create or use any existing fork by the name `github.com/user/my-org-project`.
+The fork will be created in the namespace of the user publishing the changeset, or the namespace of the service account if [global service account](/batch-changes/configuring-credentials#global-service-account-tokens) is in use. The name of the fork Sourcegraph creates will be prefixed with the name of the original repo's namespace in order to prevent potential repo name collisions. For example, a batch spec targeting `github.com/my-org/project` would create or use any existing fork by the name `github.com/user/my-org-project`.
 
 ### Examples
 
@@ -188,7 +188,7 @@ Sourcegraph can be configured to [sign commits pushed to GitHub](https://docs.gi
 
 At present, only GitHub code hosts (both Cloud and Enterprise) are supported, and only GitHub App signing is supported. Support for other code hosts and signing methods may be added in the future.
 
-GitHub Apps are also the recommended way to [sync repositories on GitHub](/admin/code_hosts/github#using-a-github-app). However, **they are not a replacement for [PATs](/batch_changes/how-tos/configuring_credentials#personal-access-tokens) in Batch Changes**. It is **also** necessary to create a separate GitHub App for Batch Changes commit signing even if you already have an App connected for the same code host for repository syncing because the Apps require different permissions. The process for creating each type of GitHub App is almost identical.
+GitHub Apps are also the recommended way to [sync repositories on GitHub](/admin/code_hosts/github#using-a-github-app). However, **they are not a replacement for [PATs](/batch-changes/configuring-credentials#personal-access-tokens) in Batch Changes**. It is **also** necessary to create a separate GitHub App for Batch Changes commit signing even if you already have an App connected for the same code host for repository syncing because the Apps require different permissions. The process for creating each type of GitHub App is almost identical.
 
 To create a GitHub App for commit signing and connect it to Sourcegraph:
 

diff --git a/docs/admin/config/webhooks/incoming.mdx b/docs/admin/config/webhooks/incoming.mdx
@@ -9,7 +9,7 @@ Webhooks are currently implemented to speed up two types of external events:
 
 See the table below for code host compatibility:
 
-          Code host           | [Batch changes](/batch_changes) | Code push | User permissions
+          Code host           | [Batch changes](/batch-changes) | Code push | User permissions
 ----------------------------- | :----------------------------------------------: | :-------: | :--------------:
 GitHub                        |                        🟢                         |     🟢     |        🟢
 GitLab                        |                        🟢                         |     🟢     |        🔴
@@ -68,7 +68,7 @@ The instructions for setting up webhooks on the code host are specific to each c
 1. Click **Add webhook**.
 1. Confirm that the new webhook is listed.
 
-Done! Sourcegraph will now receive webhook events from GitHub and use them to sync pull request events, used by [batch changes](/batch_changes/), faster and more efficiently.
+Done! Sourcegraph will now receive webhook events from GitHub and use them to sync pull request events, used by [batch changes](/batch-changes/), faster and more efficiently.
 
 #### Code push
 
@@ -101,7 +101,7 @@ When one of these events occur, a permissions sync will trigger for the relevant
 1. Click **Add webhook**.
 1. Confirm that the new webhook is listed below **Project Hooks**.
 
-Done! Sourcegraph will now receive webhook events from GitLab and use them to sync merge request events, used by [batch changes](/batch_changes/), faster and more efficiently.
+Done! Sourcegraph will now receive webhook events from GitLab and use them to sync merge request events, used by [batch changes](/batch-changes/), faster and more efficiently.
 
 **NOTE:** We currently do not support [system webhooks](https://docs.gitlab.com/ee/administration/system_hooks.html) as these provide a different set of payloads.
 
@@ -125,7 +125,7 @@ The [Sourcegraph Bitbucket Server plugin](/integration/bitbucket_server#sourcegr
    * **Secret**: The secret you configured when creating the incoming webhook.
 1. Confirm that the new webhook is listed under **All webhooks** with a timestamp in the **Last successful** column.
 
-Done! Sourcegraph will now receive webhook events from Bitbucket Server / Bitbucket Data Center and use them to sync pull request events, used by [batch changes](/batch_changes/), faster and more efficiently.
+Done! Sourcegraph will now receive webhook events from Bitbucket Server / Bitbucket Data Center and use them to sync pull request events, used by [batch changes](/batch-changes/), faster and more efficiently.
 
 #### Code push
 
@@ -146,7 +146,7 @@ Follow the same steps as above, but ensure you tick the `Push` option. If asked
 1. Click **Save**.
 1. Confirm that the new webhook is listed below **Repository hooks**.
 
-Done! Sourcegraph will now receive webhook events from Bitbucket Cloud and use them to sync pull request events, used by [batch changes](/batch_changes/), faster and more efficiently.
+Done! Sourcegraph will now receive webhook events from Bitbucket Cloud and use them to sync pull request events, used by [batch changes](/batch-changes/), faster and more efficiently.
 
 #### Code push
 
@@ -172,7 +172,7 @@ Follow the same steps as above, but ensure you tick the `Push` option.
 7. Click **Test** to verify the webhook works. Then click **Finish**.
 8. Repeat the steps above, this time choosing **Pull request merged** as your event type.
 
-Done! Sourcegraph will now receive webhook events from Azure DevOps and use them to sync pull request events, used by [batch changes](/batch_changes/), faster and more efficiently.
+Done! Sourcegraph will now receive webhook events from Azure DevOps and use them to sync pull request events, used by [batch changes](/batch-changes/), faster and more efficiently.
 
 ## Webhook logging
 

diff --git a/docs/admin/config/webhooks/outgoing.mdx b/docs/admin/config/webhooks/outgoing.mdx
@@ -4,7 +4,7 @@
 
 Outgoing webhooks can be configured on a Sourcegraph instance in order to send Sourcegraph events to external tools and services. This allows for deeper integrations between Sourcegraph and other applications.
 
-Currently, webhooks are only implemented for events related to [Batch Changes](/batch_changes/). They also cannot yet be scoped to specific entities, meaning that they will be triggered for all events of the specified type across Sourcegraph. Expanded support for more event types and scoped events is planned for the future. Please [let us know](mailto:[email protected]) what types of events you would like to see implemented next, or if you have any other feedback!
+Currently, webhooks are only implemented for events related to [Batch Changes](/batch-changes/). They also cannot yet be scoped to specific entities, meaning that they will be triggered for all events of the specified type across Sourcegraph. Expanded support for more event types and scoped events is planned for the future. Please [let us know](mailto:[email protected]) what types of events you would like to see implemented next, or if you have any other feedback!
 
 > WARNING: Outgoing webhooks have the potential to send sensitive information about your repositories and code to other untrusted services. When configuring outgoing webhooks, be sure to only send events to trusted service URLs and to use the shared secret to verify any requests received.
 

diff --git a/docs/admin/deploy/machine-images/aws-ami.mdx b/docs/admin/deploy/machine-images/aws-ami.mdx
@@ -59,7 +59,7 @@ To configure SSL, and lock down the instance from the public internet, see the [
 ### Executors
 Executors are supported using [native kubernetes executors](/admin/executors/deploy_executors_kubernetes).
 
-Executors support [auto-indexing](/code-search/code-navigation/auto_indexing) and [server-side batch changes](/batch_changes/explanations/server_side).
+Executors support [auto-indexing](/code-search/code-navigation/auto_indexing) and [server-side batch changes](/batch-changes/server-side).
 
 To enable executors you must do the following:
 1. Connect to the AMI instance using `ssh`