add DEVELOPERS.md (#73)

Cargo.toml

@@ -2,11 +2,7 @@
 name = "reddsa"
 edition = "2021"
 rust-version = "1.65"
-# When releasing to crates.io:
-# - Update CHANGELOG.md
-# - Double check if the MSRV above (rust-version field) is equal to the version
-# used in main.yml `test_msrv`
-# - Create git tag.
+# Refer to DEVELOPERS.md for guidance on making new releases.
 version = "0.5.1"
 authors = [
     "Henry de Valence <hdevalence@hdevalence.ca>",

DEVELOPERS.md

@@ -0,0 +1,49 @@
+## Release Checklist
+
+- Bump version in Cargo.toml
+- Update CHANGELOG.md
+- Ensure the MSRV in Cargo.toml (`rust-version` key) is equal to the MSRV being
+  tested (main.yml)
+- Update locked dependencies: `cargo update`. Run `cargo test --all-features`
+  to check if anything breaks. If that happens, see next section.
+- Test if it's publishable: `cargo publish --dry-run`
+- Open a PR with the version bump and changelog update, wait for review and merge
+- Tag a new release in GitHub: https://github.com/ZcashFoundation/reddsa/releases/new
+  - Create a tag with the version (e.g. `0.5.1`)
+  - Name: e.g. `0.5.1`
+  - Paste the changelog for the version
+- Publish: `cargo publish`
+
+
+## FROST
+
+FROST support is optional and enabled by the `frost` feature. It's not currently
+bound by the crate MSRV at this moment.
+
+
+## If something breaks
+
+If testing broke after running `cargo update`, first determine if it's a
+test-only dependency or not. Run `cargo build`. If that works,
+then it's probably a test-only dependency, and you can avoid updating that
+specific dependency (leave a old version in the lockfile). Otherwise investigate
+why it caused build to fail.
+
+If the "test on nightly" test failed, then either there is some bug in the code
+or some dependency update caused it to fail. Investigate and if it's the latter,
+you can either downgrade in the lockfile or try to workaround it.
+
+If the "build with no_std" test failed, then some change was introduced that
+depended on the std-library. You will probably need to fix this by changing
+to some no_std dependency, or gating the code so it only compiles when
+`std` is enabled.
+
+If one of the dependencies bumped its MSRV, we might require a MSRV bump too:
+
+- Double check if the dependency is not a test-only dependency. (The MSRV
+  test in CI only builds the library but does not test it, to prevent
+  a test-only dependency MSRV bump from breaking it.)
+- If it's not a test-only dependency, check if the main consumers of the
+  library are OK with a MSRV bump. I usually ask ECC devs.
+- If it's OK, bump it in Cargo.toml and main.yml.
+- If not, you will need to find some workaround.

README.md

@@ -54,6 +54,11 @@ This is still experimental since ZIP-312 is still a draft.
 cargo doc --features "nightly" --open
 ```
 
+## Developers guide
+
+See [DEVELOPERS.md](DEVELOPERS.md).
+
+
 [reddsa]: https://zips.z.cash/protocol/protocol.pdf#concretereddsa
 [zebra]: https://github.com/ZcashFoundation/zebra
 [refinement]: https://en.wikipedia.org/wiki/Refinement_type