proposal: use three block style for use declarations

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Rust Developer's guide to web-bot-auth
+
+Welcome to web-bot-auth's contributor guidelines. Please take a look.
+This should help you get ready to contribute to this repo.
+
+## Testing
+
+Crates in this repo provide Rust tests.
+You can run these manually using:
+
+```bash
+cargo +stable test --workspace --all-features --all-targets
+```
+
+We also target Cloudflare's worker environment. A [basic example](./examples/signature-agent-card-and-registry/)
+exists to confirm our crates work in said environment.
+Depending on your changes you might need to expand this example or create your own.
+Incompatibilities can surface only at runtime, so please exercise the example when
+your change touches the Workers path (such as adding new dependencies).
+For more information see [comment on #74](https://github.com/cloudflare/web-bot-auth/issues/74#issuecomment-4269847139)
+
+## Code Formatting
+
+Our CI runs `rustfmt` to check code formatting and `clippy` to lint.
+You can run the same yourself before submitting a PR by running:
+
+```bash
+cargo +stable fmt --workspace -- --check
+cargo +stable clippy --workspace --all-features --all-targets -- -D warnings
+```
+
+### Style
+
+Additionally, we settled on a three-block use declaration format.
+This means, use declarations (imports, in other languages) are split into
+three blocks. The first one is reserved for items provided by Rust's standard library
+(either `std`, `alloc`, or `core`). The second one is used for adding items from
+external crates (for example `serde` or `time`). The last one is used for internal
+items (`crate`, `super`, or a module).
+
+```rust
+use std::collections::HashMap;
+use std::time::Duration;
+
+use serde::Serialize;
+
+use message_signatures::MessageVerifier;
+```
+
+rather than a single ordered block:
+
+```rust
+use message_signatures::MessageVerifier;
+use serde::Serialize;
+use std::time::Duration;
+use std::collections::HashMap;
+```

crates/web-bot-auth/src/keyring.rs

@@ -1,8 +1,9 @@
+use std::collections::HashMap;
+
 use base64::{Engine as _, engine::general_purpose};
 use ed25519_dalek::{VerifyingKey, ed25519};
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
-use std::collections::HashMap;
 
 /// Errors that may be thrown by this module
 /// when importing a JWK key.

crates/web-bot-auth/src/lib.rs

@@ -25,13 +25,11 @@ pub mod keyring;
 /// Implementation of HTTP Message Signatures
 pub mod message_signatures;
 
-use components::CoveredComponent;
-use message_signatures::{MessageVerifier, ParsedLabel, SignatureTiming, SignedMessage};
-
 use data_url::DataUrl;
-use keyring::{Algorithm, JSONWebKeySet, KeyRing};
 
-use crate::components::{HTTPField, HTTPFieldParameters};
+use components::{CoveredComponent, HTTPField, HTTPFieldParameters};
+use keyring::{Algorithm, JSONWebKeySet, KeyRing};
+use message_signatures::{MessageVerifier, ParsedLabel, SignatureTiming, SignedMessage};
 
 /// Errors that may be thrown by this module.
 #[derive(Debug)]
@@ -309,13 +307,12 @@ impl WebBotAuthVerifier {
 
 #[cfg(test)]
 mod tests {
-
     use std::time::Duration;
 
-    use components::DerivedComponent;
     use indexmap::IndexMap;
 
     use super::*;
+    use components::DerivedComponent;
 
     struct StandardTestVector {}
 

crates/web-bot-auth/src/message_signatures.rs

@@ -1,13 +1,16 @@
-use super::ImplementationError;
-use crate::components::{self, CoveredComponent, HTTPField};
-use crate::keyring::{Algorithm, KeyRing};
-use indexmap::IndexMap;
-use regex::bytes::Regex;
-use sfv::SerializeValue;
 use std::fmt::Write as _;
 use std::sync::LazyLock;
 use std::time::Duration;
+
+use indexmap::IndexMap;
+use regex::bytes::Regex;
+use sfv::SerializeValue;
 use time::UtcDateTime;
+
+use super::ImplementationError;
+use crate::components::{self, CoveredComponent, HTTPField};
+use crate::keyring::{Algorithm, KeyRing};
+
 static OBSOLETE_LINE_FOLDING: LazyLock<Regex> =
     LazyLock::new(|| Regex::new(r"\s*\r\n\s+").unwrap());
 
@@ -603,11 +606,10 @@ impl MessageVerifier {
 
 #[cfg(test)]
 mod tests {
-
-    use crate::components::{DerivedComponent, HTTPField, HTTPFieldParametersSet};
     use indexmap::IndexMap;
 
     use super::*;
+    use crate::components::{DerivedComponent, HTTPField, HTTPFieldParametersSet};
 
     struct StandardTestVector {}