Merge pull request #184 from deads2k/cli-factory

add kubectl factory conventions

contributors/devel/kubectl-conventions.md

@@ -13,6 +13,7 @@ Updated: 8/27/2015
   - [Flag conventions](#flag-conventions)
   - [Output conventions](#output-conventions)
   - [Documentation conventions](#documentation-conventions)
+  - [kubectl Factory conventions](#kubectl-Factory-conventions)
   - [Command implementation conventions](#command-implementation-conventions)
   - [Generators](#generators)
 
@@ -245,6 +246,21 @@ rather than "RESOURCE" or "KIND"
 
 * Use "NAME" for resource names
 
+## kubectl Factory conventions
+
+The kubectl `Factory` is a large interface which is used to provide access to clients,
+polymorphic inspection, and polymorphic mutation.  The `Factory` is layered in
+"rings" in which one ring may reference inner rings, but not peers or outer rings.
+This is done to allow composition by extenders.
+
+In order for composers to be able to provide alternative factory implementations
+they need to provide low level pieces of *certain* functions so that when the factory
+calls back into itself it uses the custom version of the function.  Rather than try
+to enumerate everything that someone would want to override we split the factory into
+rings, where each ring can depend on methods an earlier ring, but cannot depend upon
+peer methods in its own ring.
+
+
 ## Command implementation conventions
 
 For every command there should be a `NewCmd<CommandName>` function that creates