From a6913724197f5ca0e3b9900eb849f27fcb4a9ced Mon Sep 17 00:00:00 2001
From: Matthias Felleisen <matthias@ccs.neu.edu>
Date: Sat, 2 May 2015 11:58:35 -0400
Subject: [PATCH] Jay's patch for style guide

---
 .../scribblings/style/some-performance.scrbl  | 52 +++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/pkgs/racket-doc/scribblings/style/some-performance.scrbl b/pkgs/racket-doc/scribblings/style/some-performance.scrbl
index d3c595c21c..61c01d4ded 100644
--- a/pkgs/racket-doc/scribblings/style/some-performance.scrbl
+++ b/pkgs/racket-doc/scribblings/style/some-performance.scrbl
@@ -22,6 +22,58 @@ Conversely, you should use @rkt[] (or even @rkt/gui[]) when you just want a
  convenient language to write some program. The @rkt[] language comes with
  almost all the batteries, and @rkt/gui[] adds the rest of the GUI base.
 
+@; -----------------------------------------------------------------------------
+@section{Library Interfaces}
+
+As the set of modules for a library grows, you may find that not all
+features and modules are likely to be used by all programs that use
+your library. If, by default, your library includes all features, then
+you can cause unnecessary mental stress and runtime cost for features
+that the programs do not actually use. In building the Racket
+language, we've found it useful to separate out libraries into
+different layers so users can decide which bundles they need.
+
+In Racket, the practice is to make the default (i.e. the most
+prominent name) the module that includes "everything", namely
+@rkt[]. Then, if users wish to have a smaller set of bindings, they
+can choose to use @rkt/base[], which gives an explicit name to the
+basic foundation of the library. Finally, some features are not even
+included in @rkt[], such as @racketmodname[racket/require], and must
+be required specially in all programs.
+
+Other libraries in Racket choose the default name to be the small core
+and give a special name for including everything.
+
+We encourage library developers to think critically about these
+decisions and decide on a practice that fits their taste and
+understanding of the users of their library. We encourage developers
+to use the following names for different places on the "size"
+hierarchy:
+
+@itemlist[
+
+@item{@racket[library/kernel] -- The bare minimal conceievable for
+the library to be usable. (Most libraries will not need this level.)}
+
+@item{@racket[library/base] -- A basic set of functionality.}
+
+@item{@racket[library] -- An appropriate "default" of functionality
+corresponding to either @racket[library/base] or
+@racket[library/full].}
+
+@item{@racket[library/full] -- All available functionality.}
+
+]
+
+If all Racket developers use similar names and think deeply about
+these decisions, we can make it easier for Racket users to make wise
+dependency decisions.
+
+Finally, the advice of the previous section, to use @rkt/base[] when
+building a library, generalizes to other libraries: by being more
+specific in your dependencies, you are a responsible citizen and
+enable others to have a small (transitive) dependency set.
+
 @; -----------------------------------------------------------------------------
 @section{Macros: Space and Performance}