update release checklist; misc cleanups (#843)

* update release checklist; misc cleanups

* remove links to versions

* add semver-checks; change numbered items to nonnumbered

Author: conradoplg

book/src/dev/release-checklist.md

@@ -1,110 +1,115 @@
 # Release Checklist
 
+## One-time `gh` setup
+
+Install the [GitHub command line
+tool](https://github.com/cli/cli?tab=readme-ov-file#installation) to make
+releases easier.
 
 ## One-time crates.io setup
 
-1. Follow the steps in <https://doc.rust-lang.org/cargo/reference/publishing.html#before-your-first-publish> (you can create a token scoped to `publish-update`).
-2. To get permissions to publish you’ll need to be in the [owners](https://github.com/orgs/ZcashFoundation/teams/owners) group. If you aren’t in there, ask someone in that group to add you
+- Follow the steps in <https://doc.rust-lang.org/cargo/reference/publishing.html#before-your-first-publish> (you can create a token scoped to `publish-update`).
+- To get permissions to publish you’ll need to be in the [owners](https://github.com/orgs/ZcashFoundation/teams/owners) group. If you aren’t in there, ask someone in that group to add you
 
 
 ## Communication
 
-3. Post in #frost slack channel and tag the Frost team that you’re going to be doing a release to freeze PR approvals until it’s done. E.g “@frost-core I’m doing a release of \<version> of Frost. Please do not merge any more PRs until I’m finished. Thanks.”
+- Post in #frost slack channel and tag the Frost team that you’re going to be doing a release to freeze PR approvals until it’s done. E.g “@frost-core I’m doing a release of \<version> of Frost. Please do not merge any more PRs until I’m finished. Thanks.”
 
 
 ## Checks
 
-4. Check current version for each crate. This is in the Cargo.toml file for frost-core, frost-ed448 etc.
-
-   1. [Frost core version number](https://github.com/ZcashFoundation/frost/blob/main/frost-core/Cargo.toml#L7)
-   2. [Frost ed25519 version number](https://github.com/ZcashFoundation/frost/blob/main/frost-ed25519/Cargo.toml#L8)
-   3. [Frost ed448 version number](https://github.com/ZcashFoundation/frost/blob/main/frost-ed448/Cargo.toml#L7)
-   4. [Frost p256 version number](https://github.com/ZcashFoundation/frost/blob/main/frost-p256/Cargo.toml#L8)
-   5. [Frost re randomized version number](https://github.com/ZcashFoundation/frost/blob/main/frost-rerandomized/Cargo.toml#L8)
-   6. [Frost ristretto255 version number](https://github.com/ZcashFoundation/frost/blob/main/frost-ristretto255/Cargo.toml#L8)
-   7. [Frost secp256k1 version number](https://github.com/ZcashFoundation/frost/blob/main/frost-secp256k1/Cargo.toml#L7)
-   8. [Frost secp256k1 tr version number](https://github.com/ZcashFoundation/frost/blob/main/frost-secp256k1-tr/Cargo.toml#L7)
+- Currently all crates share the same version number, in the root Cargo.toml
+   file. Take note of that version. (If we ever decide to have specific
+   versions, update those separately as required.)
 
-5. Decide which version to tag the release with (e.g. v0.3.0). Currently we always use the same release number for all crates, but it's possible for them to get out of sync in the future.
+- Decide which version to tag the release with (e.g. v0.3.0), considering
+   [SemVer](https://doc.rust-lang.org/cargo/reference/semver.html).
 
-6. Create new issue. E.g. [Release v0.4.0](https://github.com/ZcashFoundation/frost/issues/377)
+- Create new issue. E.g. [Release v0.4.0](https://github.com/ZcashFoundation/frost/issues/377)
 
 
 ## Make changes
 
-7. Bump the version of the crates in the root Cargo.toml file. (If they ever
+- Bump the version of the crates in the root Cargo.toml file. (If they ever
    get out of sync, you will need to bump in each crate Cargo.toml file.)
 
-8. Bump the version used in the tutorial (importing.md)
+- Run `cargo semver-checks` to check if there are no API changes that break
+   SemVer compatibility. ([Installation
+   instructions](https://crates.io/crates/cargo-semver-checks)) Fix issues if
+   any (i.e. change the version, or revert/adapt the API change).
+
+- Bump the version used in the tutorial (importing.md)
 
-9. Check if the [changelog](https://github.com/ZcashFoundation/frost/blob/main/frost-core/CHANGELOG.md) is up to date and update if required (we’re only keeping the one in frost-core for now). Double check using [FROST releases](https://github.com/ZcashFoundation/frost/releases) which will have a list of all the PRs that have been closed since the last release. Things to include in the changelog will be anything that impacts production code and big documentation changes. I.e. script and test changes should not be included. NOTE: Please add to the changelog whenever you make changes to the library as this will make things simpler for the person in charge of the release.
+- Check if the [changelog](https://github.com/ZcashFoundation/frost/blob/main/frost-core/CHANGELOG.md) is up to date and update if required (we’re only keeping the one in frost-core for now). Double check using [FROST releases](https://github.com/ZcashFoundation/frost/releases) which will have a list of all the PRs that have been closed since the last release. Things to include in the changelog will be anything that impacts production code and big documentation changes. I.e. script and test changes should not be included. NOTE: Please add to the changelog whenever you make changes to the library as this will make things simpler for the person in charge of the release.
 
-   1. Move version in changelog to Released
-   2. Create a new version in “unreleased” in changelog
+   - Move version in changelog to Released
+   - Create a new version in “unreleased” in changelog
 
-10. Update the version number for frost-core and frost-rerandomized in the Ciphersuite crates, e.g. in `frost-core = { path = "../frost-core", version = "0.4.0", features = ["test-impl"] }`. You'll need to do this for dependencies and dev-dependencies
+- Update the version number for frost-core and frost-rerandomized in the Ciphersuite crates, e.g. in `frost-core = { path = "../frost-core", version = "0.4.0", features = ["test-impl"] }`. You'll need to do this for dependencies and dev-dependencies
 
-11. Create a PR with subject `Release \<version number>` containing all these changes
+- Create a PR with subject `Release \<version number>` containing all these changes
 
-12. You’ll need someone to review and approve it
+- You’ll need someone to review and approve it
 
-13. Wait for it to pass CI checks
+- Wait for it to pass CI checks
 
 
 ## Publish
 
-14. Checkout main branch, **in the commit of the previously merged PR** (in case other stuff got merged after that)
+- Checkout main branch, **in the commit of the previously merged PR** (in case other stuff got merged after that)
 
-15. Run `cargo publish -p frost-core --dry-run` to check if it’s ready to publish. Fix issues if any.
+- Run `cargo publish -p frost-core --dry-run` to check if it’s ready to publish. Fix issues if any.
 
-16. [Draft and publish a new release](https://github.com/ZcashFoundation/frost/releases/new) for frost-core.
+- [Draft and publish a new release](https://github.com/ZcashFoundation/frost/releases/new) for frost-core.
 
-    1. In “Choose a tag” type `<crate>/<version>` e.g. “frost-core/v0.2.0” and click “Create new tag”
-    2. In “Target” select “main” as long as other PRs haven’t been merged after the version bump PR. Otherwise, **select the commit matching the PR that was merged above**.
-    3. In “Release title” use `<crate> <version>` e.g. “frost-core v0.2.0”
-    4. Paste the (raw Markdown) changelog for this version into the description box.
-    5. Leave “Set as pre-release” **unchecked** (we should have checked it in earlier versions but the ship has sailed. It doesn’t matter much)
-    6. **Check** “Set as the latest release”
+    - In “Choose a tag” type `<crate>/<version>` e.g. “frost-core/v0.2.0” and click “Create new tag”
+    - In “Target” select “main” as long as other PRs haven’t been merged after the version bump PR. Otherwise, **select the commit matching the PR that was merged above**.
+    - In “Release title” use `<crate> <version>` e.g. “frost-core v0.2.0”
+    - Paste the (raw Markdown) changelog for this version into the description box.
+    - Leave “Set as pre-release” **unchecked** (we should have checked it in earlier versions but the ship has sailed. It doesn’t matter much)
+    - **Check** “Set as the latest release”
 
-17. Publish it with `cargo publish -p frost-core`
+- Publish it with `cargo publish -p frost-core`
 
-18. Check if frost-rerandomized is ready to be published: `cargo publish -p frost-rerandomized --dry-run`. Fix any errors if needed.
+- Check if frost-rerandomized is ready to be published: `cargo publish -p frost-rerandomized --dry-run`. Fix any errors if needed.
 
-19. Draft and publish a frost-rerandomized release
+- Draft and publish a frost-rerandomized release:
 
-    1. Use the same process as described for frost-core above, but you can leave the changelog empty and **uncheck** “Set as the latest release”
+    - Run `gh release create "frost-rerandomized/v2.1.0" -n '' -t "frost-rerandomized v2.1.0" --latest=false`
+       (replace both instances of the version)
 
-20. Publish it with `cargo publish -p frost-rerandomized`
+- Publish it with `cargo publish -p frost-rerandomized`
 
-21. Check if other crates are ready to be published: `for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs --dry-run; done`. Fix any issues if needed.
+- Check if other crates are ready to be published: `for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs --dry-run; done`. Fix any issues if needed.
 
-    1. If you get an error like this:
+    - If you get an error like this:
 
        “error: failed to verify package tarball Caused by: failed to select a version for the requirement `frost-core = "^0.3.0"` candidate versions found which didn't match: 0.2.0, 0.1.0 location searched: crates.io index required by package `frost-ed25519 v0.3.0 (frost/target/package/frost-ed25519-0.3.0)`”
 
        This is because the ciphersuite crates aren’t pointing at the new frost-core package. This is because you need to publish frost-core before you can publish the others otherwise they will not have the expected version to point to.
 
-22. Draft and publish releases for each of those crates (sorry, that will be boring)
+- Draft and publish releases for each of those crates:
 
-    1. Use the same process as described for frost-core above (actions 1 - 3), but you can leave the changelog empty and **uncheck** “Set as the latest release”
+    - Run `for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do gh release create "frost-$cs/v2.1.0" -n '' -t "frost-$cs v2.1.0" --latest=false; done` (replace both instances of the version)
 
-23. Publish those crates: `for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs; done`
+- Publish those crates: `for cs in ristretto255 ed25519 secp256k1 secp256k1-tr p256 ed448; do cargo publish -p frost-$cs; done`
 
 
 ## Confirm
 
-24. Check versions in the crates to confirm everything worked:
+- Check versions in the crates to confirm everything worked:
 
-    1. [Frost core](https://crates.io/crates/frost-core/versions)
-    2. [Frost ed25519](https://crates.io/crates/frost-ed25519/versions)
-    3. [Frost ed448](https://crates.io/crates/frost-ed448/versions)
-    4. [Frost p256](https://crates.io/crates/frost-p256/versions)
-    5. [Frost ristretto255](https://crates.io/crates/frost-ristretto255/versions)
-    6. [Frost secp256k1](https://crates.io/crates/frost-secp256k1/versions)
-    7. [Frost secp256k1 tr](https://crates.io/crates/frost-secp256k1-tr/versions)
-    8. [Frost rerandomized](https://crates.io/crates/frost-rerandomized/versions)
+    - [Frost core](https://crates.io/crates/frost-core/versions)
+    - [Frost ed25519](https://crates.io/crates/frost-ed25519/versions)
+    - [Frost ed448](https://crates.io/crates/frost-ed448/versions)
+    - [Frost p256](https://crates.io/crates/frost-p256/versions)
+    - [Frost ristretto255](https://crates.io/crates/frost-ristretto255/versions)
+    - [Frost secp256k1](https://crates.io/crates/frost-secp256k1/versions)
+    - [Frost secp256k1 tr](https://crates.io/crates/frost-secp256k1-tr/versions)
+    - [Frost rerandomized](https://crates.io/crates/frost-rerandomized/versions)
 
-25. Let the team know in the #frost slack channel that the release is complete and successful
+- Let the team know in the #frost slack channel that the release is complete and successful
 
 
 ## In the case of an unsuccessful release

frost-core/CHANGELOG.md

@@ -8,9 +8,9 @@ Entries are listed in reverse chronological order.
 
 * It is now possible to identify the culprit in `frost_core::keys::dkg::part3()`
   if an invalid secret share was sent by one of the participants (by calling
-  frost_core::Error<C>::culprit()`) (#728)
+  `frost_core::Error<C>::culprit()`) (#728)
 * Added frost-secp256k1-tr crate, allowing to generate Bitcoin Taproot
-  (BIP340/BIP341) compatible signatures(#730).
+  (BIP340/BIP341) compatible signatures (#730).
 * Support refreshing shares using the DKG approach using the
   `frost_core::keys::refresh::refresh_dkg_{part1,part2,shares}()` functions
   (#766).

frost-core/src/keys/refresh.rs

@@ -1,8 +1,8 @@
 //! Refresh Shares
 //!
-//! Implements the functionality to refresh a share. This requires the participation
-//! of all the remaining signers. This can be done using a Trusted Dealer or
-//! DKG (not yet implemented)
+//! Implements the functionality to refresh a share. This requires the
+//! participation of all the remaining signers. This can be done using a Trusted
+//! Dealer or DKG.
 
 use alloc::collections::BTreeMap;
 use alloc::vec::Vec;