Improve documentation based on review in #d-release

Signed-off-by: Niels Thykier <niels@thykier.net>

doc/migrations-simplified.md

@@ -5,7 +5,7 @@
 
 This is a technical introduction to how britney
 handles migrations.  Being an introduction, it deliberately
-oversimplify certain things at the expense of accuracy.
+oversimplifies certain things at the expense of accuracy.
 It also covers common migration issues and how to fix
 them.
 
@@ -24,48 +24,53 @@ Debian-based distribution practises and terminology (such as
 ## A high level overview of britney and migrations
 
 The purpose of britney is to (semi-)automatically select
-a number of package groups from a series of source suites
+a number of migration items from a series of source suites
 (e.g. Debian unstable) that are ready to migrate to
 the target suite (e.g. Debian testing).
 
 The definition of "ready" can be summarized as satisfying all
 of the following points:
 
- 1. The package groups pass a number of policies for the target
+ 1. The migration items pass a number of policies for the target
     suite.  Most of these policies are basically that the
-    package groups do not regress on selected QA checks.
+    migration items do not regress on selected QA checks.
-    * A group satisfying this part is called a `valid candiate`.
+    * An item satisfying this part is called a `valid candiate`.
  1. Installability will not regress as a result of
-    migrating the package groups.
+    migrating the migration items.
-    * A group that (also) satisfy this will be selected for migration.
+    * An item that (also) satisfies this part will be selected
+      for migration.
 
-The keyword in both points being *regress*.  If a package
+The keyword in both points being *regress*.  If a package has an
-has an existing issue in the target suite, a group with the
+existing issue in the target suite, the item including a new version
-new version is generally allowed to migrate if it has the
+of that package is generally allowed to migrate if it has the same
-same issue (as it is not a regression).
+issue (as it is not a regression).
 
-This only leaves the definition of a package group.  In britney,
+This only leaves the definition of a migration items.  They come
-these groups are known as "migration items" and they come in
+in several variants defined in the next section.
-several variants.  These will be explained in the next section
 
 ## Migration items
 
-Internally, britney groups packages into "migration items"
+Internally, britney groups packages into migration items based on a
-based on a few rules.  Every upload of a source package will
+few rules.  There are several kinds of migration items and this
-be associated with a *source migration item*.  As the binary
+document will only describe the source migration item.
-packages are built and uploaded, they will be included into
+
-the migration item and various QA checks/policies will be
+>  A source migration item is one upload of a source package, with
-applied to the item.
+>  associated binary packages once built.
+
+Once a new version of a source package appears in the source suite,
+britney will create track it with a source migration item.  As the
+binary packages are built and uploaded, they will be included into the
+migration item and various QA checks/policies will be applied to the
+item.
 
 Once britney deems the item ready, she will attempt to
 migrate the item (i.e. source with its binaries) to the 
 target suite.
 
 
-There are several other migration types.  But they are
+As implied earlier, there are several other migration types.  But they
-not covered in this document as the primary audience
+are not covered in this document.  They deal with cases like removals,
-of this document will generally not need to know about
+rebuilds of existing binaries, etc.
-them to begin with.
 
 ## Migration phase 1: Policies / Excuses
 
@@ -138,8 +143,8 @@ the excuses.
 ### Confirming a migration
 
 To start with; if a migration is accepted and "committed" (i.e. it will not
-be rolled back), britney will include in a line starting with `final:` a la
+be rolled back), britney will include in a line starting with `final:` like
-this example:
+in this example:
 
     Apparently successful
     final: -cwltool,-libtest-redisserver-perl,-pinfo,-webdis,hol88