Small crates

README.md

@@ -33,7 +33,7 @@ language.
 * [Entry API](patterns/entry.md)
 * [Visitor](patterns/visitor.md)
 * [Fold](patterns/fold.md)
-* TODO small crates and semver
+* [Prefer small crates](patterns/small-crates.md)
 * TODO extension traits
 * TODO destructor bombs (ensure linear typing dynamically, e.g., https://github.com/Munksgaard/session-types/commit/0f25ccb7c3bc9f65fa8eaf538233e8fe344a189a)
 * TODO convertible to Foo trait for more generic generics (e.g., http://static.rust-lang.org/doc/master/std/fs/struct.File.html#method.open)

patterns/small-crates.md

@@ -0,0 +1,31 @@
+# Prefer small crates
+
+## Description
+
+Prefer small crates that do one thing well.
+
+Cargo and crates.io make it easy to add third-party libraries, much more so than in say C or C++. We should take advantage of this tooling, and use smaller, more fine-grained dependencies.
+
+## Advantages
+
+* Small crates are easier to understand and audit.
+* Since the compilation unit of Rust is the crate, splitting a project into multiple crates can allow more of the code to be built in parallel.
+* If published on crates.io, a crate can be reused by other projects.
+
+## Disadvantages
+
+* Too many crates can lead to code that is hard to follow.
+* This can lead to "dependency hell", where a project depends on multiple conflicting versions of a crate at the same time.
+* Packages on crates.io are not curated. A crate may be poorly written, have unhelpful documentation, or be outright malicious.
+
+## Examples
+
+The [`ref_slice`](https://crates.io/crates/ref_slice) crate provides functions for converting `&T` to `&[T]`.
+
+The [`url`](https://crates.io/crates/url) crate provides tools for working with URLs.
+
+The [`png`](https://crates.io/crates/png) crate decodes PNG image files.
+
+## See also
+
+* [crates.io: The Rust community crate host](https://crates.io/)