diff options
author | Pietro Albini <pietro@pietroalbini.org> | 2019-02-25 15:07:56 +0100 |
---|---|---|
committer | Pietro Albini <pietro@pietroalbini.org> | 2019-02-25 15:20:04 +0100 |
commit | 3bc6edd71fe5db86a61950cb4bf1f725f0b1a11e (patch) | |
tree | c30c3a0be78a7343111dc8e0ec5b6f99071cda77 | |
parent | a8cfd4daec1cf5240e488bd448441be5ed4a9726 (diff) |
docs: improve readme and move toml schema to its own page
-rw-r--r-- | README.md | 107 | ||||
-rw-r--r-- | docs/toml-schema.md | 89 |
2 files changed, 109 insertions, 87 deletions
@@ -3,14 +3,26 @@ This repository contains the structure of the Rust teams. The repository is automatically synchronized with: -* [Governance section on the website](https://www.rust-lang.org/governance) -* [Crater and @craterbot](https://github.com/rust-lang-nursery/crater) -* Mailing lists and aliases for `@rust-lang.org` and `@crates.io` +| Service | Synchronized every | | +| --- | :---: | --- | +| [Crater and @craterbot][crater] | *In real time* | [Integration source][crater-src] | +| Mailing lists and aliases (`@rust-lang.org`, `@crates.io`) | 5 minutes | [Integration source][ml-src] +| [Governance section on the website][www] | 2 minutes | [Integration source][www-src] | If you need to add or remove a person from a team send a PR to this repository, and after it's merged their account will be added/removed from all the supported services. +[www]: https://www.rust-lang.org/governance +[www-src]: https://github.com/rust-lang/www.rust-lang.org/blob/master/src/teams.rs +[crater]: https://github.com/rust-lang-nursery/crater +[crater-src]: https://github.com/rust-lang-nursery/crater/blob/master/src/server/auth.rs +[ml-src]: https://github.com/rust-lang/rust-central-station/tree/master/sync-mailgun + +## Documentation + +* [TOML schema reference](docs/toml-schema.md) + ## Using the CLI tool It's possible to interact with this repository through its CLI tool. @@ -47,92 +59,13 @@ You can get a list of all the users with a permission: $ cargo run dump-permission perf ``` -## Schema - -### People - -Every member of a Rust team is represented by a file in the `people` directory. -The file structure is this: +### Building the static API -```toml -name = "John Doe" # Real name of the person (required) -github = "johndoe" # GitHub username of the person (required) -# You can also set `email = false` to explicitly disable the email for the user. -# This will, for example, avoid adding the person to the mailing lists. -email = "john@doe.com" # Email address used for mailing lists (optional) -irc-nickname = "jdoe" # Nickname of the person on IRC, if different than the GitHub one (optional) +You can build locally the content of `https://team-api.infra.rust-lang.org/v1/` +by running the command: -[permissions] -# Optional, see the permissions documentation ``` - -The file must be named the same as the GitHub username. - -### Teams - -Each Rust team or working group is represented by a file in the `teams` -directory. The structure of the file is this: - -```toml -name = "overlords" # Name of the team, used for GitHub (required) -subteam-of = "gods" # Name of the parent team of this team (optional) - -[people] -# Leads of the team, can be more than one and must be members of the team. -# Required, but it can be empty -leads = ["bors"] -# Members of the team, can be empty -members = [ - "bors", - "rust-highfive", - "rfcbot", - "craterbot", - "rust-timer", -] - -[permissions] -# Optional, see the permissions documentation - -# Define the mailing lists used by the team -# It's optional, and there can be more than one -[[lists]] -# The email address of the list (required) -address = "overlords@rust-lang.org" -# Access level of the list (required) -# - readonly: only users authenticated with Mailgun can send mails -# - members: only members of the list can send mails -# - everyone: everyone can send mails -access-level = "everyone" -# This can be set to false to avoid including all the team members in the list -# It's useful if you want to create the list with a different set of members -# It's optional, and the default is `true`. -include-team-members = true -# Include the following extra people in the mailing list. Their email address -# will be fetched from theirs TOML in people/ (optional). -extra-people = [ - "alexcrichton", -] -# Include the following email addresses in the mailing list (optional). -extra-emails = [ - "noreply@rust-lang.org", -] -# Include all the memebrs of the following teams in the mailing list -# (optional). -extra-teams = [ - "bots-nursery", -] +$ cargo run static-api output-dir/ ``` -### Permissions - -Permissions can be applied either to a single person or to a whole team, and -they grant access to some pieces of rust-lang tooling. The following -permissions are available: - -```toml -[permissions] -# Optional, grants access to the @rust-timer GitHub bot -perf = true -# Optional, grants access to the @craterbot GitHub bot -crater = true -``` +The content will be placed in `output-dir/`. diff --git a/docs/toml-schema.md b/docs/toml-schema.md new file mode 100644 index 0000000..0ea6abb --- /dev/null +++ b/docs/toml-schema.md @@ -0,0 +1,89 @@ +# TOML schema reference + +## People + +Every member of a Rust team is represented by a file in the `people` directory. +The file structure is this: + +```toml +name = "John Doe" # Real name of the person (required) +github = "johndoe" # GitHub username of the person (required) +# You can also set `email = false` to explicitly disable the email for the user. +# This will, for example, avoid adding the person to the mailing lists. +email = "john@doe.com" # Email address used for mailing lists (optional) +irc-nickname = "jdoe" # Nickname of the person on IRC, if different than the GitHub one (optional) + +[permissions] +# Optional, see the permissions documentation +``` + +The file must be named the same as the GitHub username. + +## Teams + +Each Rust team or working group is represented by a file in the `teams` +directory. The structure of the file is this: + +```toml +name = "overlords" # Name of the team, used for GitHub (required) +subteam-of = "gods" # Name of the parent team of this team (optional) + +[people] +# Leads of the team, can be more than one and must be members of the team. +# Required, but it can be empty +leads = ["bors"] +# Members of the team, can be empty +members = [ + "bors", + "rust-highfive", + "rfcbot", + "craterbot", + "rust-timer", +] + +[permissions] +# Optional, see the permissions documentation + +# Define the mailing lists used by the team +# It's optional, and there can be more than one +[[lists]] +# The email address of the list (required) +address = "overlords@rust-lang.org" +# Access level of the list (required) +# - readonly: only users authenticated with Mailgun can send mails +# - members: only members of the list can send mails +# - everyone: everyone can send mails +access-level = "everyone" +# This can be set to false to avoid including all the team members in the list +# It's useful if you want to create the list with a different set of members +# It's optional, and the default is `true`. +include-team-members = true +# Include the following extra people in the mailing list. Their email address +# will be fetched from theirs TOML in people/ (optional). +extra-people = [ + "alexcrichton", +] +# Include the following email addresses in the mailing list (optional). +extra-emails = [ + "noreply@rust-lang.org", +] +# Include all the memebrs of the following teams in the mailing list +# (optional). +extra-teams = [ + "bots-nursery", +] +``` + +## Permissions + +Permissions can be applied either to a single person or to a whole team, and +they grant access to some pieces of rust-lang tooling. The following +permissions are available: + +```toml +[permissions] +# Optional, grants access to the @rust-timer GitHub bot +perf = true +# Optional, grants access to the @craterbot GitHub bot +crater = true +``` |