From 92f20931e8c4096e1933ba1bc5596d33fde96e48 Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 18 Sep 2023 10:06:11 +1000 Subject: [PATCH 1/5] Add instructions for changing crate owners --- book/src/dev/crate-owners.md | 91 ++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 book/src/dev/crate-owners.md diff --git a/book/src/dev/crate-owners.md b/book/src/dev/crate-owners.md new file mode 100644 index 00000000000..98b461469ee --- /dev/null +++ b/book/src/dev/crate-owners.md @@ -0,0 +1,91 @@ +# 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`) +- 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). + +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; 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 +~ +~/zebra-client ~ + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of 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 +``` + +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; 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 +~/zebra +~/zebra/tower-fallback ~/zebra + Updating crates.io index + Owner user oxarbitrage has been invited to be an owner of crate tower-fallback +~/zebra +... +``` From d9005532cfbfaa8e39e2721b14ecd023e0a9daf8 Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 18 Sep 2023 10:08:38 +1000 Subject: [PATCH 2/5] Explain new owner invites --- book/src/dev/crate-owners.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/book/src/dev/crate-owners.md b/book/src/dev/crate-owners.md index 98b461469ee..154b6fab96c 100644 --- a/book/src/dev/crate-owners.md +++ b/book/src/dev/crate-owners.md @@ -46,6 +46,8 @@ Zcash Foundation crates should have: 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: From 0c14ef09287d65033375fb3fb072af62e51168f8 Mon Sep 17 00:00:00 2001 From: teor Date: Mon, 18 Sep 2023 10:10:47 +1000 Subject: [PATCH 3/5] Remove duplicate `cargo login` instructions from the release checklist --- .github/PULL_REQUEST_TEMPLATE/release-checklist.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE/release-checklist.md b/.github/PULL_REQUEST_TEMPLATE/release-checklist.md index d7cf1ffebb6..f51ae3bb18a 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`: From 1fe7d437deb6312c05989e8ae0af09d276339da8 Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 19 Sep 2023 05:39:11 +1000 Subject: [PATCH 4/5] Remove owners as well --- book/src/dev/crate-owners.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/book/src/dev/crate-owners.md b/book/src/dev/crate-owners.md index 154b6fab96c..ef70705f44e 100644 --- a/book/src/dev/crate-owners.md +++ b/book/src/dev/crate-owners.md @@ -6,7 +6,7 @@ Zcash Foundation crates are controlled by the [`ZcashFoundation/owners`](https:/ 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`) +- starts with `zebra` (including `zebrad` and the `zebra` placeholder) - starts with `tower` We also depend on these separate ZF crates: @@ -54,15 +54,19 @@ 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; popd; done +$ 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 ~ ~/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 ~ ... ``` @@ -74,20 +78,27 @@ $ 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; popd; done +$ 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 ... ``` From 068b0aa840239724e97b7f864bc573754189b1cf Mon Sep 17 00:00:00 2001 From: teor Date: Tue, 19 Sep 2023 05:40:17 +1000 Subject: [PATCH 5/5] Missing log line --- book/src/dev/crate-owners.md | 1 + 1 file changed, 1 insertion(+) diff --git a/book/src/dev/crate-owners.md b/book/src/dev/crate-owners.md index ef70705f44e..88a3460aa88 100644 --- a/book/src/dev/crate-owners.md +++ b/book/src/dev/crate-owners.md @@ -62,6 +62,7 @@ $ for crate in tower-batch-cpu zebra zebra-cli zebra-client; do cargo new $crate 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