From dbdb4be429dd7cef8c87c9f0e2cad3497bf3c5fe Mon Sep 17 00:00:00 2001 From: teor Date: Wed, 20 Sep 2023 10:40:48 +1000 Subject: [PATCH] add(doc): Add instructions for changing crate owners (#7572) * Add instructions for changing crate owners * Explain new owner invites * Remove duplicate `cargo login` instructions from the release checklist * Remove owners as well * Missing log line --- .../release-checklist.md | 12 +- book/src/dev/crate-owners.md | 105 ++++++++++++++++++ 2 files changed, 108 insertions(+), 9 deletions(-) create mode 100644 book/src/dev/crate-owners.md diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index d7cf1ffe..f51ae3bb 100644 --- a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md +++ b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md @@ -75,14 +75,8 @@ Zebra's Rust API doesn't have any support or stability guarantees, so we keep al ### Update Crate Versions -
- -If you're publishing crates for the first time, click this triangle for extra steps - -- [ ] Install `cargo-release`: `cargo install cargo-release` -- [ ] Make sure you are an owner of the crate or [a member of the Zebra crates.io `owners` group on GitHub](https://github.com/orgs/ZcashFoundation/teams/owners) - -
+If you're publishing crates for the first time, [log in to crates.io](https://github.com/ZcashFoundation/zebra/blob/doc-crate-own/book/src/dev/crate-owners.md#logging-in-to-cratesio), +and make sure you're a member of owners group. Check that the release will work: - [ ] Update crate versions, commit the changes to the release branch, and do a release dry-run: @@ -145,7 +139,7 @@ The end of support height is calculated from the current blockchain height: ## Publish Crates -- [ ] Run `cargo login` +- [ ] [Run `cargo login`](https://github.com/ZcashFoundation/zebra/blob/doc-crate-own/book/src/dev/crate-owners.md#logging-in-to-cratesio) - [ ] Run `cargo clean` in the zebra repo (optional) - [ ] Publish the crates to crates.io: `cargo release publish --verbose --workspace --execute` - [ ] Check that Zebra can be installed from `crates.io`: diff --git a/book/src/dev/crate-owners.md b/book/src/dev/crate-owners.md new file mode 100644 index 00000000..88a3460a --- /dev/null +++ b/book/src/dev/crate-owners.md @@ -0,0 +1,105 @@ +# Zebra Crates + +The Zebra project publishes around 20 crates to the Rust [crates.io website](https://crates.io). +Zcash Foundation crates are controlled by the [`ZcashFoundation/owners`](https://github.com/orgs/ZcashFoundation/teams/owners) GitHub team. + +The latest list of Zebra and FROST crates is [available on crates.io](https://crates.io/teams/github:zcashfoundation:owners). + +The Zebra repository can be used to publish the crates in this list that match these patterns: +- starts with `zebra` (including `zebrad` and the `zebra` placeholder) +- starts with `tower` + +We also depend on these separate ZF crates: +- `zcash_script` +- `ed25519-zebra` + +And these crates shared with ECC: +- `reddsa` +- `redjubjub` + +## Logging in to crates.io + +To publish a crate or change owners, you'll need to [log in to crates.io](https://doc.rust-lang.org/cargo/reference/publishing.html#before-your-first-publish) using `cargo login`. + +When you create a token, give it an expiry date, and limit its permissions to the task you're doing. For example, if you're doing a release, create a token for releasing crates. + +Tokens that allow changing owners should have the shortest expiry possible. + +[Revoke the token](https://crates.io/me) after you're finished using it. + +Here is an example login command: +```sh +$ cargo login +please paste the token found on https://crates.io/me below +... + Login token for `crates.io` saved +``` + +## Crate Ownership + +crates.io has two kinds of owners: group owners and individual owners. All owners can publish and yank crates. +But [only individual owners can change crate owners](https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner). + +Zcash Foundation crates should have: +- at least 2 individual owners, who are typically engineers on the relevant project +- a group owner that contains everyone who can publish the crate + +When an individual owner leaves the foundation, they should be [replaced with another individual owner](https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner). + +New crate owners should go to [crates.io/me](https://crates.io/me) to accept the invitation, then they will appear on the list of owners. + +Here are some example commands for changing owners: + +To change owners of deleted/placeholder Zebra crates: +```sh +$ mkdir placeholders +$ cd placeholders +$ for crate in tower-batch-cpu zebra zebra-cli zebra-client; do cargo new $crate; pushd $crate; cargo owner --add oxarbitrage; cargo owner --remove dconnolly; popd; done + Created binary (application) `zebra-cli` package +~/zebra-cli ~ + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of crate zebra-cli + Updating crates.io index + Owner removing ["dconnolly"] from crate zebra-cli +~ + Created binary (application) `zebra-client` package +~/zebra-client ~ + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of crate zebra-client + Updating crates.io index + Owner removing ["dconnolly"] from crate zebra-client +~ +... +``` + +To change owners of `zcash_script`: +```sh +$ git clone https://github.com/ZcashFoundation/zcash_script +$ cd zcash_script +$ cargo owner --add oxarbitrage + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of crate zcash_script +$ cargo owner --remove dconnolly + Updating crates.io index + Owner removing ["dconnolly"] from crate zcash_script +``` + +To change owners of current Zebra crates: +```sh +$ git clone https://github.com/ZcashFoundation/zebra +$ cd zebra +$ for crate in tower-* zebra*; do pushd $crate; cargo owner --add oxarbitrage; cargo owner --remove dconnolly; popd; done +~/zebra/tower-batch-control ~/zebra + Updating crates.io index + Owner user oxarbitrage already has a pending invitation to be an owner of crate tower-batch-control + Updating crates.io index + Owner removing ["dconnolly"] from crate tower-batch-control +~/zebra +~/zebra/tower-fallback ~/zebra + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of crate tower-fallback + Updating crates.io index + Owner removing ["dconnolly"] from crate tower-fallback +~/zebra +... +```