Skip to content

Commit eb39e7d

Browse files
courier-newcourier-new
authored
batches: update docs, in-app changelog for 4.1 (sourcegraph#43066)
1 parent 934f34f commit eb39e7d

File tree

8 files changed

+141
-9
lines changed

8 files changed

+141
-9
lines changed

‎CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ All notable changes to Sourcegraph are documented in this file.
2323
- Batch changes run on the server can now be created within organisations. [#36536](https://github.com/sourcegraph/sourcegraph/issues/36536)
2424
- GraphQL request logs are now compliant with the audit logging format. The old GraphQl logging based on `LOG_ALL_GRAPHQL_REQUESTS` env var is now deprecated and scheduled for removal. [#42550](https://github.com/sourcegraph/sourcegraph/pull/42550)
2525
- Mounting files now works when running batch changes server side. [#31792](https://github.com/sourcegraph/sourcegraph/issues/31792)
26+
- Added mini dashboard of total batch change metrics to the top of the batch changes list page. [#42046](https://github.com/sourcegraph/sourcegraph/pull/42046)
2627

2728
### Changed
2829

‎client/web/src/enterprise/batches/list/BatchChangesChangelogAlert.tsx

+19-5
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import React from 'react'
22

33
import classNames from 'classnames'
44

5-
import { CardBody, Card, H3, H4 } from '@sourcegraph/wildcard'
5+
import { CardBody, Card, H3, H4, Link } from '@sourcegraph/wildcard'
66

77
import { DismissibleAlert } from '../../../components/DismissibleAlert'
88

@@ -11,15 +11,29 @@ import styles from './BatchChangesListIntro.module.scss'
1111
export const BatchChangesChangelogAlert: React.FunctionComponent<React.PropsWithChildren<unknown>> = () => (
1212
<DismissibleAlert
1313
className={styles.batchChangesListIntroAlert}
14-
partialStorageKey="batch-changes-list-intro-changelog-4.0"
14+
partialStorageKey="batch-changes-list-intro-changelog-4.1"
1515
>
1616
<Card className={classNames(styles.batchChangesListIntroCard, 'h-100')}>
1717
<CardBody>
18-
<H4 as={H3}>Batch Changes updates in version 4.0</H4>
18+
<H4 as={H3}>Batch Changes updates in version 4.1</H4>
1919
<ul className="mb-0 pl-3">
2020
<li>
21-
Code host connection tokens are no longer supported as a fallback method for syncing changesets
22-
in Batch Changes.
21+
Batch changes run on the server can now be created within{' '}
22+
<Link
23+
to="/help/batch_changes/how-tos/creating_a_batch_change#creating-a-batch-change-in-a-different-namespace"
24+
rel="noopener"
25+
target="_blank"
26+
>
27+
organizations
28+
</Link>
29+
.
30+
</li>
31+
<li>
32+
Batch changes run on the server now support{' '}
33+
<Link to="/help/batch_changes/how-tos/server_side_file_mounts" rel="noopener" target="_blank">
34+
mounting files
35+
</Link>
36+
.
2337
</li>
2438
</ul>
2539
</CardBody>

‎client/web/src/enterprise/batches/list/BatchChangesListIntro.tsx

+17-4
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ import { CardBody, Card, Link, H4, Text } from '@sourcegraph/wildcard'
66

77
import { SourcegraphIcon } from '../../../auth/icons'
88

9+
import { BatchChangesChangelogAlert } from './BatchChangesChangelogAlert'
10+
911
import styles from './BatchChangesListIntro.module.scss'
1012

1113
export interface BatchChangesListIntroProps {
@@ -15,15 +17,26 @@ export interface BatchChangesListIntroProps {
1517
export const BatchChangesListIntro: React.FunctionComponent<React.PropsWithChildren<BatchChangesListIntroProps>> = ({
1618
isLicensed,
1719
}) => {
18-
if (isLicensed === undefined || isLicensed === true) {
20+
if (isLicensed === undefined) {
1921
return null
2022
}
2123

2224
return (
2325
<div className="row">
24-
<div className="col-12 mb-3">
25-
<BatchChangesUnlicensedAlert />
26-
</div>
26+
{isLicensed === true ? (
27+
<div className="col-12">
28+
<BatchChangesChangelogAlert />
29+
</div>
30+
) : (
31+
<>
32+
<div className="col-12 col-md-6 mb-3">
33+
<BatchChangesUnlicensedAlert />
34+
</div>
35+
<div className="col-12 col-md-6 mb-3">
36+
<BatchChangesChangelogAlert />
37+
</div>
38+
</>
39+
)}
2740
</div>
2841
)
2942
}

‎doc/batch_changes/how-tos/creating_a_batch_change.md

+13
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ Batch changes are created by writing a [batch spec](../references/batch_spec_yam
44

55
Batch changes can also be used on [multiple projects within a monorepo](./creating_changesets_per_project_in_monorepos.md) by using the `workspaces` key in your batch spec.
66

7+
There are two paths to creating a batch change:
8+
9+
- On your local machine, with the [Sourcegraph CLI](https://github.com/sourcegraph/src-cli)
10+
- Remotely, with [server-side execution](../explanations/server_side.md)
11+
12+
Many concepts are shared between the two paths. However, this guide will walk you through creating a batch change the first way, on your local machine.
13+
714
## Requirements
815

916
- Sourcegraph instance with repositories in it. See the "[Quickstart](../../index.md#quick-install)" guide on how to setup a Sourcegraph instance.
@@ -91,3 +98,9 @@ By default, batch changes will use your username on Sourcegraph as your namespac
9198
```
9299
src batch preview -f your_batch_spec.batch.yaml -namespace USERNAME_OR_ORG
93100
```
101+
102+
When creating a batch change server-side using the UI, you can select the namespace for the batch change to belong to at the time that you're creating it.
103+
104+
### Administration
105+
106+
Once a batch change is open, any Sourcegraph user can view it. However, the namespace determines who has the ability to 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.

‎doc/batch_changes/how-tos/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ The following is a list of how-tos that show how to use [Sourcegraph Batch Chang
1313
- [Changeset yaml formatting errors](yaml_changeset_errors.md)
1414
- [Opting out of Batch Changes](opting_out_of_batch_changes.md)
1515
- [Bulk operations on changesets](bulk_operations_on_changesets.md)
16+
- <span class="badge badge-experimental">Experimental</span> [Using file mounts with server-side execution](server_side_file_mounts.md)
1617
- Batch changes in monorepos
1718
- [Creating changesets per project in monorepos](creating_changesets_per_project_in_monorepos.md)
1819
- <span class="badge badge-experimental">Experimental</span> [Creating multiple changesets in large repositories](creating_multiple_changesets_in_large_repositories.md)

‎doc/batch_changes/how-tos/server_side_file_mounts.md

+87
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Using file mounts with server-side execution
2+
3+
<aside class="experimental">
4+
<p>
5+
<span class="badge badge-experimental">Experimental</span> This feature is experimental and might change or be removed in the future. We've released it as an experimental feature to provide a preview of functionality we're working on.
6+
</p>
7+
8+
<p><b>We're very much looking for input and feedback on this feature.</b> You can either <a href="https://about.sourcegraph.com/contact">contact us directly</a>, <a href="https://github.com/sourcegraph/sourcegraph">file an issue</a>, or <a href="https://twitter.com/sourcegraph">tweet at us</a>.</p>
9+
10+
<p>This feature is available in Sourcegraph 4.1 with <a href="https://github.com/sourcegraph/src-cli">Sourcegraph CLI</a> 4.0.1 and later.</p>
11+
</aside>
12+
13+
> NOTE: Running a batch spec [server-side](../explanations/server_side.md) with file mounts is
14+
> currently only supported with <a href="https://github.com/sourcegraph/src-cli">Sourcegraph CLI</a>.
15+
16+
File [`mounts`](../references/batch_spec_yaml_reference.md#steps-mount) are a powerful way to run custom files without
17+
directly embedding the files in your batch spec.
18+
19+
## Writing a batch spec
20+
21+
In the following example, you have a Python script that appends "Hello World" to all `README.md` files.
22+
23+
```python
24+
#!/usr/bin/env python3
25+
import os.path
26+
27+
28+
def main():
29+
if os.path.exists('README.md'):
30+
with open('README.md', 'a') as f:
31+
f.write('\nHello World')
32+
33+
34+
if __name__ == "__main__":
35+
main()
36+
```
37+
38+
To use the Python script in your batch change, mount the script in a `step` using
39+
the [`mounts`](../references/batch_spec_yaml_reference.md#steps-mount) field. The following is an example of mounting
40+
the above Python script in a `step`.
41+
42+
```yaml
43+
name: hello-world
44+
description: Add Hello World to READMEs
45+
46+
# Find all repositories that contain a README.md file.
47+
on:
48+
- repositoriesMatchingQuery: file:README.md
49+
50+
# In each repository, run this command. Each repository's resulting diff is captured.
51+
steps:
52+
- run: python /tmp/hello_appender.py
53+
container: python:latest
54+
mount:
55+
- path: ./hello_appender.py
56+
mountpoint: /tmp/hello_appender.py
57+
58+
# Describe the changeset (e.g., GitHub pull request) you want for each repository.
59+
changesetTemplate:
60+
title: Hello World
61+
body: My first batch change!
62+
branch: hello-world # Push the commit to this branch.
63+
commit:
64+
message: Append Hello World to all README.md files
65+
published: false # Do not publish any changes to the code hosts yet
66+
```
67+
68+
In this example, the Python script should live besides the batch spec file, as indicated by the `path`:
69+
70+
```text
71+
.
72+
├── batch-spec.yml
73+
└── hello_appender.py
74+
```
75+
76+
Note that a `container` appropriate for the mounted file has also been chosen for this step.
77+
78+
## Running server-side
79+
80+
After writing the batch spec, use the <a href="https://github.com/sourcegraph/src-cli">Sourcegraph CLI (`src`)</a>
81+
command [`remote`](../../cli/references/batch/remote.md) to execute the batch spec server-side.
82+
83+
```shell
84+
src batch remote -f batch-spec.yml
85+
```
86+
87+
Once successful, `src` provides a URL to the execution of the batch change.

‎doc/batch_changes/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ Create a batch change by specifying a search query to get a list of repositories
8989
- [Handling errored changesets](how-tos/handling_errored_changesets.md)
9090
- [Opting out of batch changes](how-tos/opting_out_of_batch_changes.md)
9191
- [Bulk operations on changesets](how-tos/bulk_operations_on_changesets.md)
92+
- <span class="badge badge-experimental">Experimental</span> [Using file mounts with server-side execution](how-tos/server_side_file_mounts.md)
9293
- Batch changes in monorepos <span class="badge badge-experimental">Experimental</span>
9394
- [Creating changesets per project in monorepos](how-tos/creating_changesets_per_project_in_monorepos.md)
9495
- <span class="badge badge-experimental">Experimental</span> [Creating multiple changesets in large repositories](how-tos/creating_multiple_changesets_in_large_repositories.md)

‎doc/batch_changes/references/batch_spec_yaml_reference.md

+2
Original file line numberDiff line numberDiff line change
@@ -433,6 +433,8 @@ path is absolute or relative, the path must be within the same directory as the
433433
spec directory is considered the "working directory"). If the batch spec is provided using standard input, the current
434434
directory is used as the working directory.
435435

436+
Individual files are restricted to a max size of 10MB. Do not include any sensitive information in files being uploaded.
437+
436438
### Examples
437439

438440
```yaml

0 commit comments

Comments
 (0)