add concepts.rst, fix broken link in code.rst

custom_conf.py

@@ -127,7 +127,6 @@
     'https://wiki.canonical.com/InformationInfrastructure/OSA/LPHowTo/ManualCdImageMirrorProber',  # private
     'Trunk/Glue',  # needs update
     '/Background', 
-    '/Concepts',  # needs update
     '/HowToUseCodehostingLocally',  # needs update
     'Database/TableRenamePatch',  # needs update
     'Debugging#Profiling%20page%20requests',  # needs update

explanation/code.rst

@@ -136,9 +136,7 @@ kicked off.
 The web application
 -------------------
 
-Code that is executed as part of the Launchpad web application. The core
-`concepts </Concepts>`__ are documented on the
-`Code/Concepts </Concepts>`__ page.
+Code that is executed as part of the Launchpad web application. The core concepts are documented on the :doc:`Code Concepts <./concepts>` page.
 
 **Major features**
 

explanation/concepts.rst

@@ -0,0 +1,148 @@
+Code Concepts
+=============
+
+In order to fully understand the **\`lp.code\`** modules, it helps to
+have an understanding of a number of core concepts.
+
+Registry objects are those Launchpad-wide objects that are shared
+between the different Launchpad applications. The registry objects that
+**\`lp.code\`** modules are associated with are:
+
+-  Person
+-  Product
+-  Project
+-  !SourcePackage
+-  Distribution
+-  !DistroSeries
+-  !DistributionSourcePackage
+
+``  ''Please be aware of the confusion between ``\ *:literal:`\`Products\``*\ `` and ``\ *:literal:`\`Projects\``*\ `` in the codebase.  To the outside world a ``\ *:literal:`\`Product\``*\ `` is a project, and a ``\ *:literal:`\`Project\``*\ `` is a project group (or super-project).''``
+
+There are a few major concepts in **\`lp.code\`** to do with branches:
+
+-  `Branch <#branch>`__
+-  `Merge proposal <#merge-proposal>`__
+-  `Namespace <#namespace>`__
+-  `Target <#target>`__
+-  `Collection <#collection>`__
+
+<<Anchor(branch)>>
+
+Branch
+------
+
+The branch object in Launchpad refers to a real Bazaar branch.
+
+A branch has an owner. The owner can be either an individual or a team.
+The owner defines who can write to the branch.
+
+A branch also has a target. There are three current targets:
+
+-  !PersonBranchTarget - these are \`+junk\` branches
+-  !ProductBranchTarget - these are branches associated with a product,
+   sometimes called an upstream
+-  !PackageBranchTarget - these branches are associated with source
+   packages. A source package is effectively tuple of a particular
+   package name in a distribution series.
+
+You almost never need to know about these objects though, since they are
+!IBranchTarget adapters: \`IBranchTarget(person)`,
+\`IBranchTarget(product)`, \`IBranchTarget(source_package)`.
+
+A branch also has a name.
+
+Together the owner, target and name make the \`unique_name\` of the
+branch.
+
+<<Anchor(merge-proposal)>>
+
+Merge proposal
+--------------
+
+A merge proposal (`BranchMergeProposal`) is used to record information
+around the process of merging one branch into another.
+
+In situations where feature branches are used, it is normal for each
+feature branch to have a merge proposal for the main trunk branch. In
+these cases the feature branch is the \`source_branch`, and the trunk is
+the \`target_branch`.
+
+The code review process happens around a merge proposal. People can
+review and comment on the proposal, and proposals can be approved (or
+rejected) to land on the target branch.
+
+<<Anchor(namespace)>>
+
+Namespace
+---------
+
+A namespace is (usually?) an owner and a target.
+
+A namespace has exactly one branch collection associated with it. In
+some sense, it **is** a branch collection. (is-a could mean inheritance
+or adaptation).
+
+A namespace is, conceptually, everything up to the last part of a
+branch's unique name.
+
+There's no hierarchy of branches beneath a namespace.
+
+A branch belongs to exactly one namespace.
+
+::
+
+   IBranchNamespace
+     target :: IBranchTarget
+     getBranches() :: [IBranch]
+     createBranch(*args) :: IBranch
+
+<<Anchor(target)>>
+
+Target
+------
+
+**Target** is the most nebulous of these concepts. A target is a thing a
+branch is a branch \*of*, or perhaps a thing a branch lives on. A
+product is a target, a source package is a target, a person's +junk area
+is a target. A project (i.e. a collection of products) is not a target.
+
+Each branch has exactly one target.
+
+A target is not a namespace (in general). A +junk target is, at some
+level, a namespace, but other targets are not (only because +junk is
+associated with a person).
+
+A target has a collection naturally associated with it: the collection
+of all branches with that target. Does this mean a target is, in some
+sense, a collection? Probably not.
+
+::
+
+   IBranchTarget
+     context :: (registry object)
+     collection :: IBranchCollection
+     default_stacked_on_branch :: IBranch
+     default_merge_target :: IBranch
+     getNamespace(person) :: IBranchNamespace
+     -- implemented by BranchTarget only.
+
+<<Anchor(collection)>>
+
+Collection
+----------
+
+A collection has no semantic value beyond being a collection. It need
+not be tied to a specific registry object, namespace or target. "All
+branches" is a special, well-known branch collection. A collection is
+simply a clear API for "a bunch of branches". A collection is the
+preferred way of talking about a bunch of branches in our code-base.
+
+::
+
+   IBranchCollection
+     getBranches
+     getMergeProposals
+      - implemented using getBranches,
+      - merge proposals where the source branch is in getBranches()
+     # separately,
+     # a bunch of filter methods.