Skip to content

Commit 0c89d17

Browse files
KobzolKobzol
committed
Update documentation
1 parent 7b4a90b commit 0c89d17

File tree

2 files changed

+61
-68
lines changed

2 files changed

+61
-68
lines changed

‎README.md

Lines changed: 58 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,45 @@
33
This repository contains the structure of the Rust teams. The repository is
44
automatically synchronized with:
55

6-
| Service | Synchronized every | |
7-
| --- | :---: | --- |
8-
| [@bors][bors] | *In real time* | [Integration source][bors-src] |
9-
| [Crater and @craterbot][crater] | *In real time* | [Integration source][crater-src] |
10-
| [Perf and @rust-timer][perf] | *In real time* | [Integration source][perf-src] |
11-
| [@rfcbot][rfcbot] | 5 minutes | [Integration source][rfcbot-src] |
12-
| GitHub teams membership | *Shortly after merge* | [Integration source][sync-team-src] |
13-
| GitHub repositories | *Shortly after merge* | [Integration source][sync-team-src] |
14-
| Mailing lists and aliases (`@rust-lang.org`, `@crates.io`) | *Shortly after merge* | [Integration source][sync-team-src] |
15-
| Zulip user group membership | *Shortly after merge* | [Integration source][sync-team-src] |
16-
| [Governance section on the website][www] | 2 minutes | [Integration source][www-src] |
17-
| crates.io admin access | 1 hour | [Integration source][crates-io-admin-src] |
6+
| Service | Synchronized every | |
7+
|------------------------------------------------------------|:---------------------:|-------------------------------------------|
8+
| [@bors][bors] | *In real time* | [Integration source][bors-src] |
9+
| [Crater and @craterbot][crater] | *In real time* | [Integration source][crater-src] |
10+
| [Perf and @rust-timer][perf] | *In real time* | [Integration source][perf-src] |
11+
| [@rfcbot][rfcbot] | 5 minutes | [Integration source][rfcbot-src] |
12+
| GitHub teams membership | *Shortly after merge* | [Integration source][sync-team-src] |
13+
| GitHub repositories | *Shortly after merge* | [Integration source][sync-team-src] |
14+
| Mailing lists and aliases (`@rust-lang.org`, `@crates.io`) | *Shortly after merge* | [Integration source][sync-team-src] |
15+
| Zulip user group membership | *Shortly after merge* | [Integration source][sync-team-src] |
16+
| [Governance section on the website][www] | 2 minutes | [Integration source][www-src] |
17+
| crates.io admin access | 1 hour | [Integration source][crates-io-admin-src] |
1818

1919
If you need to add or remove a person from a team, send a PR to this
20-
repository. After it's merged, their account will be added/removed
20+
repository. After it's merged, their account will be added/removed
2121
from all the supported services.
2222

2323
[bors]: https://buildbot2.rust-lang.org/homu
24+
2425
[bors-src]: https://github.com/rust-lang/homu/blob/master/homu/auth.py
26+
2527
[www]: https://www.rust-lang.org/governance
28+
2629
[www-src]: https://github.com/rust-lang/www.rust-lang.org/blob/master/src/teams.rs
30+
2731
[crater]: https://github.com/rust-lang-nursery/crater
32+
2833
[crater-src]: https://github.com/rust-lang-nursery/crater/blob/master/src/server/auth.rs
34+
2935
[perf]: https://perf.rust-lang.org
36+
3037
[perf-src]: https://github.com/rust-lang-nursery/rustc-perf/blob/master/site/src/server.rs
38+
3139
[rfcbot]: https://rfcbot.rs
40+
3241
[rfcbot-src]: https://github.com/anp/rfcbot-rs/blob/master/src/teams.rs
42+
3343
[sync-team-src]: https://github.com/rust-lang/sync-team
44+
3445
[crates-io-admin-src]: https://github.com/rust-lang/crates.io/blob/main/src/worker/jobs/sync_admins.rs
3546

3647
## Documentation
@@ -94,7 +105,6 @@ You can get a list of all the users with a permission:
94105
cargo run dump-permission perf
95106
```
96107

97-
98108
You can generate [www.rust-lang.org](https://github.com/rust-lang/www.rust-lang.org)'s locales/en-US/tools.ftl file by running
99109

100110
```
@@ -113,7 +123,6 @@ cargo run dump-individual-access --group-mode repo
113123
cargo run dump-individual-access --group-mode person
114124
```
115125

116-
117126
### Building the static API
118127

119128
You can build locally the content of `https://team-api.infra.rust-lang.org/v1/`
@@ -125,6 +134,40 @@ cargo run static-api output-dir/
125134

126135
The content will be placed in `output-dir/`.
127136

137+
### Syncing the state
138+
139+
You can use the tool to synchronize state to the live services. By default, the tool will run in *dry mode* on all the services we synchronize, meaning that the changes will be previewed on the console output but no actual change will be applied:
140+
141+
```
142+
cargo run sync
143+
```
144+
145+
Once you're satisfied with the changes you can run the full synchronization by
146+
passing the `apply` subcommand:
147+
148+
```
149+
cargo run sync apply
150+
```
151+
152+
You can also limit the services to synchronize on by passing a list of all the
153+
service names you want to sync. For example, to synchronize only GitHub and
154+
Mailgun you can run:
155+
156+
```
157+
cargo run sync -- --services github,mailgun
158+
cargo run sync -- --services github,mailgun apply
159+
```
160+
161+
By default, the synchronization will be based on data from the live `team` endpoint.
162+
When making changes to the tool it might be useful to test
163+
with dummy data though. You can do that by passing the `--team-repo` flag to the CLI:
164+
165+
```
166+
cargo run sync -- --team-json <directory>
167+
```
168+
169+
The `<directory>` with JSON data can be generated using `cargo run static-api`.
170+
128171
### Encrypting email addresses
129172

130173
If an email address in a list needs to be confidential it's possible to encrypt

‎sync-team/README.md

Lines changed: 3 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,10 @@
1-
# Team synchronization tool
1+
# Team synchronization code
22

3-
This repository contains the CLI tool used to synchronize the contents of the
4-
[rust-lang/team] repository with some of the services the Rust Team uses. There
5-
is usually no need to run this tool manually, and running it requires elevated
6-
privileges on our infrastructure.
3+
This crate contains code used to synchronize the contents of the
4+
team data with some of the services the Rust Team uses.
75

86
| Service name | Description | Environment variables |
97
|--------------|-------------------------------------------------|---------------------------------------------|
108
| github | Synchronize GitHub teams and repo configuration | `GITHUB_TOKEN` |
119
| mailgun | Synchronize mailing lists on Mailgun | `MAILGUN_API_TOKEN`, `EMAIL_ENCRYPTION_KEY` |
1210
| zulip | Synchronize Zulip user groups | `ZULIP_USERNAME`, `ZULIP_API_TOKEN` |
13-
14-
The contents of this repository are available under both the MIT and Apache 2.0
15-
license.
16-
17-
## Running the tool
18-
19-
By default the tool will run in *dry mode* on all the services we synchronize,
20-
meaning that the changes will be previewed on the console output but no actual
21-
change will be applied:
22-
23-
```
24-
cargo run
25-
```
26-
27-
Once you're satisfied with the changes you can run the full synchronization by
28-
passing the `apply` subcommand:
29-
30-
```
31-
cargo run apply
32-
```
33-
34-
You can also limit the services to synchronize on by passing a list of all the
35-
service names you want to sync. For example, to synchronize only GitHub and
36-
Mailgun you can run:
37-
38-
```
39-
cargo run -- --services github,mailgun
40-
cargo run -- --services github,mailgun apply
41-
```
42-
43-
## Using a local copy of the team repository
44-
45-
By default, this tool works on the production dataset, pulled from
46-
[rust-lang/team]. When making changes to the tool it might be useful to test
47-
with dummy data though. You can do that by making the changes in a local copy
48-
of the team repository and passing the `--team-repo` flag to the CLI:
49-
50-
```
51-
cargo run -- --team-repo ~/code/rust-lang/team
52-
```
53-
54-
When `--team-repo` is passed, the CLI will build the Static API in a temporary
55-
directory, and fetch the data from it instead of the production instance.
56-
57-
You can also use `--team-json` to directly pass a path to a directory containing
58-
the JSON output generated by the `team` repo.
59-
60-
[rust-lang/team]: https://github.com/rust-lang/team

0 commit comments

Comments
 (0)