repo -> codebase, rework content, diagram

content/abstract.md

@@ -1,12 +1,12 @@
 Abtract
 =======
 
-Modern software is almost always delivered as a service: called *web apps*, or *software-as-a-service*.  The twelve-factor app is a methodology for building software-as-a-service apps that:
+Today, software is almost always delivered as a service: called *web apps*, or *software-as-a-service*.  The twelve-factor app is a methodology for building software-as-a-service apps that:
 
-* Use **declarative** formats for setup **automation**, to minimize time and cost of a new developer joining the project;
+* Use **declarative** formats for setup **automation**, to minimize time and cost for new developers joining the project;
 * Have a **clean contract** with the underlying operating system, offering **maximum portability** between execution environments;
 * Are suitable for **deployment** on modern **cloud platforms**, obviating the need for servers and systems administration;
-* **Minimize divergence** between development and production, **enabling continuous** deployment for maximum agility;
+* **Minimize divergence** between development and production, enabling **continuous deployment** for maximum agility;
 * And can **scale up** without significant changes to tooling, architecture, or development practices.
 
 The twelve-factor methodology can be applied to apps written in any programming language, and which use any combination of backing services (database, queue, memory cache, etc).

content/codebase.md

@@ -0,0 +1,18 @@
+## I. Codebase
+### One codebase tracked in revision control, many deploys
+
+A twelve-factor app is always tracked in a version control system, such as [Git](http://git-scm.com/), [Mercurial](http://mercurial.selenic.com/), or [Subversion](http://subversion.apache.org/).  An copy of the revision tracking database is known as a *code repository*, often shortened to *code repo* or just *repo*.
+
+A *codebase* is any single repo (in a centralized revision control system like Subversion), or any set of repos who share a root commit (in a decentralized revision control system like Git).
+
+![One codebase maps to many deploys](/images/codebase-deploys.png)
+
+There is always a one-to-one correlation between the codebase and the app:
+
+* If there are multiple codebases, it's not an app - it's a distributed system.  Each component in a distributed system is an app, and each can individually comply with twelve-factor.
+* Multiple apps sharing the same code is a violation of twelve-factor.  The solution for that case is to factor shared code into libraries which can be included through the [dependency manager](/dependencies).
+
+There is only one codebase per app, but there will be many deploys of the app.  A *deploy* is a running instance of the app.  This is typically a production site, and one or more staging sites.  Additionally, every developer has a copy of the app running in their local development environment, each of which also qualifies as a deploy.
+
+The codebase is the same across all deploys, although different versions may be active in each deploy.  For example, a developer has some commits not yet deployed to staging; staging has some commits not yet deployed to production.  But they all share the same codebase, thus making them identifiable as different versions of the same app 
+

content/repo.md

@@ -1,11 +0,0 @@
-## I. Repo
-### One code repo, many deploys
-
-A twelve-factor app is always tracked in a version control system, with the tracked code history known as a *code reposistory*, often shortened to *code repo* or just *repo*.
-
-There is always a one-to-one correlation between the repo and the app.  If there are multiple code repos, it's not an app - it's a distributed system.  Multiple apps sharing the same code is a violation of twelve-factor and generally poor practice.  In the latter case, the better approach is to factor shared code libraries which can be included through the [dependency manager](#).
-
-There is only one repo per app, but there will be many deploys of the app.  A *deploy* is a running instance of the app.  This is typically one production site, and one or more staging sites.  Every developer working on the app has their own local version which also qualifies as a deploy, though one visible only to that developer and only useful for editing the app's code.
-
-The repo is the same across all deploys, although different versions may be active in each deploy.  For example, a developer has some commits not yet deployed to staging; staging has some commits not yet deployed to production.  But they all share the same revision history tree.
-

content/toc.md

@@ -1,8 +1,8 @@
 The Twelve Factors
 ==================
 
-## [I. Repo](/repo)
-### One code repo, many deploys
+## [I. Codebase](/codebase)
+### One codebase tracked in revision control, many deploys
 
 ## [II. Dependencies](/dependencies)
 ### Explicit dependency declaration and isolation

content/who.md

@@ -1,4 +1,4 @@
 Who should read this document?
 ==============================
 
-Any developer building applications run as a service, and ops engineers who deploy or run such applications.
+Any developer building applications run as a service.  Ops engineers who deploy or run such applications.

public/style.css

@@ -40,12 +40,12 @@ article {
   text-align: justify;
   width: 60em;
 }
-article p a {
+article p a, article li a {
   text-decoration: none;
   border-bottom: 1px dashed #444;
   color: #000;
 }
-article p a:hover {
+article p a:hover, article li a:hover {
   color: #337;
 }
 
@@ -102,6 +102,7 @@ section#factor h3 {
 #next a, #prev a {
   font-size: 22pt;
   text-decoration: none;
+  color: #555;
 }
 
 code {
@@ -126,3 +127,8 @@ footer {
   padding-bottom: 16pt;
   text-align: center;
 }
+
+article img {
+  float: right;
+  margin-left: 32pt;
+}

views/layout.erb

@@ -16,7 +16,7 @@
 </head>
 <body>
   <header>
-    <img src="/symbol.png" />
+    <img src="/images/symbol.png" />
     <h1><a href="/">The Twelve-Factor App</a></h1>
   </header>
 

web.rb

@@ -5,7 +5,7 @@ get '/' do
   erb :home
 end
 
-TOC = %w(repo dependencies config backing-services build-release-run processes port-binding concurrency dev-prod-parity logs admin-processes)
+TOC = %w(codebase dependencies config backing-services build-release-run processes port-binding concurrency dev-prod-parity logs admin-processes)
 
 get '/:factor' do |factor|
   @factor = factor