roadmap to v1.0.0?

[rursprung]

do you have a roadmap to releasing a v1.0.0? it would be cool if you could create the tickets for what you think is missing for v1.0.0 and assign them to a v1.0.0 milestone.

rationale: theoretically, one should only build on released software, so using 0.x pre-releases for production software isn't looked on too well. in the rust eco-system there are sadly a lot of crates which stay on 0.x for years but are heavily used. having a roadmap helps in understanding why a crate is not yet released as 1.x (or higher) and allows analysing the trade-offs (is it acceptable to use the crate in production even though these features are missing?).

furthermore, this would help with contributors: they know where work still needs to be done and they can offer their help focused on these topics.

specifically this seems to block the heapless crate from releasing an 1.0.0 release: rust-embedded/heapless#410 (comment)

with over 9 million downloads the hash32 crate is heavily used in the (embedded) rust ecosystem (see also the dependent crates, primarily through heapless) and having a stable release would be beneficial for all of them.

this crate seems to be very stable (no open issues, only one open PR, no commits since a year), indicating that it'd be a good candidate for an 1.0.0 release (either just re-release the last release as 1.0.0 or optionally include some cleanups along with it if needed).

[newAM]

Similar to heapless 1.0 I would like to go through a checklist: rust-embedded/heapless#535

I'm very busy with work recently, but I'll try to get started this week. I don't expect this to take long, as mentioned this crate is very stable without a lot of activity.

Checklist

• Review allowed warnings and clippy lints
  • murmur3: remove #[allow(deprecated)] #31

  • hash32/src/murmur3.rs

    Line 211 in a49d0a4

    #[allow(clippy::trivially_copy_pass_by_ref)]

• Review non-default clippy lints (-W clippy::pedantic -W clippy::nursery)
  • Add clippy to CI, address some non-default lints #26
• Review explicit panics, unwraps, expects in non-test code
• Review crate features
• grep for fixme, todo, xxx, ect.

  • hash32/src/murmur3.rs

    Line 189 in a49d0a4

    // XXX is this faster?

  • murmur3: address todo in code #40
• Review open issues
• Review open pull-requests
• Improve test coverage
  • Add test vectors for Murmur3Hasher #24
  • Add test vectors for FnvHasher #25

Rust API Guidelines Checklist

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
  • Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • Getter names follow Rust convention (C-GETTER)
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • Iterator type names match the methods that produce them (C-ITER-TY)
  • Feature names are free of placeholder words (C-FEATURE)
  • Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
    • std::hash::DefaultHasher implements Debug and Clone.
    • hashers: derive Debug and Clone #39
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • Collections implement FromIterator and Extend (C-COLLECT)
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • Types are Send and Sync where possible (C-SEND-SYNC)
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output (C-EVOCATIVE)
  • Macros compose well with attributes (C-MACRO-ATTR)
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
  • Item macros support visibility specifiers (C-MACRO-VIS)
  • Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
    • lib.rs: doc: rework #38
  • All items have a rustdoc example (C-EXAMPLE)
    • Hasher: Add example #35
    • Add examples for all remaining docstrings. #37
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      keywords, categories
  • Release notes document all significant changes (C-RELNOTES)
    • CHANGELOG: add entry for edition change #33
  • Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods (C-SMART-PTR)
  • Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • Functions with a clear receiver are methods (C-METHOD)
  • Functions do not take out-parameters (C-NO-OUT)
  • Operator overloads are unsurprising (C-OVERLOAD)
  • Only smart pointers implement Deref and DerefMut (C-DEREF)
  • Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • Caller decides where to copy and place data (C-CALLER-CONTROL)
  • Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions (C-NEWTYPE)
  • Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
  • Destructors never fail (C-DTOR-FAIL)
  • Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug (C-DEBUG)
    • hashers: derive Debug and Clone #39
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)
  • Structs have private fields (C-STRUCT-PRIVATE)
  • Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable (C-STABLE)
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)

Dependencies

• remove byteorder, Remove byteorder dependency #22

Questions

• What should the MSRV policy look like?
  • I think Ferrocene support is important for some users, this is currently at 1.83.0
  • upgrade to rust 2021 edition #18

[rursprung]

i'd add one more point to the checklist: add test coverage. currently there's 0 test coverage. i'd expect a 1.0 crate to come with a reasonable set of tests to ensure that there won't be any unexpected breakage in the future.

(note: i have no stake in this library and have never used it directly. i came across this because of heapless, which has it as a dependency and i was interested in that reaching 1.0)

[eldruin]

It is now published! Thank you everybody! 🎉