byteorder-partial-eval.md

byteorder evaluation 2017-02-18

Prep checklist

• Compare crate to guidelines
• Draft tracking issue
• Update guidelines
• Update cookbook

Guidelines checklist

• Naming
• Architecture
• Containers
• Ownership and resource management
• Error handling
• Documentation
  • [n] All items have a rustdoc example (C-EXAMPLES)
  • [n] Function docs include panic conditions in "Panics" section (C-PANIC-DOC)
  • [n] Function docs include error conditions in "Errors" section (C-ERROR-DOC)
  • [n] Cargo.toml includes common headers (C-CARGO-HEADERS)
    • authors, description, documentation, homepage
    • repository, readme, keywords, categories, license
    • missing "categories"
  • [n] Cargo.toml publishes CI badges for tier 1 platforms (C-CI)
• Unsorted guidelines
  • [y] Eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd
    • Hash Debug, Display
    • Yes, but should these be implemented for phantom types?
  • [y] All public types implement Debug (C-DEBUG)
  • [-] All public types implement serde Serialize / Deserialize (C-SERDE)
    • No, but for phantom types?
  • [-] Crate has a serde cfg option that enables serde (C-SERDE-CFG)
    • No, but should it for a crate with no serializable types?
  • [y] Public dependencies must be stable (C-PUB-DEP)
  • [y] Crate and its dependencies have a permissive license (C-PERMISSIVE)

Tracking issue

• BigEndian and LittleEndian example (C-EXAMPLES)
• ByteOrder panic doc sections (C-PANIC-DOC)
• ReadBytesExt error doc sections (C-ERROR-DOC)
• WriteBytesExt error doc sections (C-ERROR-DOC)
• NativeEndian and LittleEndian examples (C-EXAMPLES)
• Add CI badges to Cargo.toml (C-CI)
• Add "categories" to Cargo.toml (C-CARGO-HEADERS)

Notes and questions

All types are phantom types. No guidelines. It uses pub enum BigEndian {}. Is this the correct formulation? Any other phantom concerns?

These types don't implement Default, but they are uninhabitable. We have no Default guidelines, but we implement it a lot.

These phantom types implement all common traits. Why?

Likewise, should this crate do anything with serde?

What's the purpose of write_uint / write_int?

This crate sets it's "documentation" key to docs.rs. Should we put it in the guidelines? (Yes!)

Should we say anything about the readme?

Dev-deps are unstable.

This crate defines a Result typedef. Is this a best practice we should use across the board?

This crate is missing inline rustdoc links. Should we add them and make that a criteria?

Evaluation notes for byteorder

• examples
  • not on everything
  • practical guidelines
• phantom types have common impls
  • even for phantom types, because of derive generates trait constraints
  • adding more common traits will be a breaking change because the ByteOrder trait won't implement them
  • serde_json uses a private supertrait to encapsulate this
  • do we want to block 1.0 on a supertrait? "sealed trait"

action items

• do what with phantom types and supertrait?
• update guidelines with example guidelines
• ByteOrder::default should panic! not unreachable!
• no serde for byteorder
• add serde guidelines - use good judgement - between Debug and Display
• add guideline encouraging docs.rs unless there's a reason not to
• add guideline always have #[doc(html_root)]
• add tracking issue to use #[doc(html_root)]