Log libz-blitz evaluation tracker

[alexcrichton]

log evaluation for 2017-05-16

For more information see the internals libz blitz thread.

This post is a wiki. Feel free to edit it.

Links

• https://crates.io/crates/log
• https://github.com/rust-lang-nursery/log
• https://docs.rs/log

Pre-review checklist

Do these before the libs team review.

• Create evaluation thread based on this template
• Work with author and issue tracker to identify known blockers
• Compare crate to guidelines by filling in checklist
• Record other questions and notes about crate
• Draft several use case statements to serve as cookbook examples
• Record recommendations for updated guidelines
• Publish evaluation to coordination thread for review and notify reviewers

Post-review checklist

Do these after the libs team review.

• Publish libs team meeting video
• Create new issues and tracking issue on crate's issue tracker
• Solicit use cases for cookbook examples related to the crate
• File bugs to implement cookbook examples
• File bugs to update guidelines
• Post all approachable issues to twir call for participation thread
• Update links in coordination thread

Guidelines checklist

• Organization (crate is structured in an intelligible way)
  • Crate root re-exports common functionality ([C-REEXPORT])
  • Modules provide a sensible API hierarchy ([C-HIERARCHY])
• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 ([C-CASE])
  • Ad-hoc conversions follow as_, to_, into_ conventions ([C-CONV])
  • 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])
  • Ownership suffixes use _mut and _ref ([C-OWN-SUFFIX])
  • Single-element containers implement appropriate getters ([C-GETTERS])
• 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
  • 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])
  • Crate has a "serde" cfg option that enables Serde ([C-SERDE-CFG])
  • Types are Send and Sync where possible ([C-SEND-SYNC])
  • Error types are Send and Sync ([C-SEND-SYNC-ERR])
  • Error types are meaningful, not () ([C-MEANINGFUL-ERR])
  • Binary number types provide Hex, Octal, Binary formatting ([C-NUM-FMT])
• 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])
  • All items have a rustdoc example ([C-EXAMPLE])
  • Examples use ?, not try!, not unwrap ([C-QUESTION-MARK])
  • Function docs include error conditions in "Errors" section ([C-ERROR-DOC])
  • Function docs include panic conditions in "Panics" section ([C-PANIC-DOC])
  • Prose contains hyperlinks to relevant things ([C-LINK])
  • Cargo.toml publishes CI badges for tier 1 platforms ([C-CI])
  • Cargo.toml includes all common metadata ([C-METADATA])
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/$crate/$version" ([C-HTML-ROOT])
  • Cargo.toml documentation key points to "https://docs.rs/$crate" ([C-DOCS-RS])
• 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])
  • Deref and DerefMut never fail ([C-DEREF-FAIL])
  • 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])
  • Debug representation is never empty ([C-DEBUG-NONEMPTY])
• Future proofing (crate is free to improve without breaking users' code)
  • Structs have private fields ([C-STRUCT-PRIVATE])
  • Newtypes encapsulate implementation details ([C-NEWTYPE-HIDE])
• 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])

Cookbook use case statements

• Debug messages
• Logging info/error messages
• Logging levels per module
• Linux syslog logging

Crate issues

(List potential issues here)

Style guide updates

(List potential updates to the style guide)

Discussion topics

(List new questions that arose from this evaluation)

[dpc]

First link seem point to 404

[alexcrichton]

Ah yes sorry I opened this in the wrong place, there's shortly be a thread on internals to replace this.

[dpc]

That is a cool list. I'd be interested in copying and use it. Is there any more information about it that I could use?

[alexcrichton]

Ok there's now a thread on internals as well as this thread copied there too. If you've got any questions/thoughts, please feel free to post there!

[brson]

@dpc Here's the list: https://github.com/brson/rust-api-guidelines