@@ -51,5 +51,64 @@ build by running:
51 cabal install stackage
51 cabal install stackage
52 stackage nightly
52 stackage nightly
54−The code itself
54+## Processing
56+The following describes at a high level the series of steps for processing
60+1. Get list of core packages
61+2. Get build constraints from list of maintained packages
62+3. Load up package index
63+4. Calculate build plan using newest versions of packages
64+5. Write out a YAML file with complete build plan
65+6. Verify that the build plan can be compiled
70+1. Load up most recent build plan
71+2. Convert build plan into constraints for next build
72+3. Continue from step (3) above
76+We start off with *constraints*. Constraints state things like "package X has a
77+given version range," who the maintainer is for a package, the description of
78+the system/compiler being used, etc. `BuildConstraints` describes the build as
79+a whole, whereas `PackageConstraints` describes the constraints on an
82+There are two primary ways of getting a `BuildConstraints`.
83+`defaultBuildConstraints` inspects the first GHC in the PATH environment variable to
84+determine GHC version, core packages, core tools, etc. It then uses the
85+`Stackage.Config` module to extract information on additional packages to be
86+installed. The secondary approach is in `Stackage2.UpdateBuildPlan`, which will be
89+`BuildConstraints` does not specify a build completely. That is given by a
90+`BuildPlan`, which is similarly broken down into `BuildPlan` and `PackagePlan`.
91+In order to get a `BuildPlan`, we need two pieces of information: the
92+`BuildConstraints`, and a package index. The package index (usually downloaded
93+from Hackage) is a collection of all of the cabal files available.
95+By applying a `BuildConstraints` to a package index (via `newBuildPlan`), we
96+get a proposed `BuildPlan`. There is no guarantee that this `BuildPlan` is
97+valid. To validate it, we use `checkBuildPlan`. A `BuildPlan` is an instance of
98+both `ToJSON` and `FromJSON`, and therefore can be serialized to a file for
101+When dealing with LTS Haskell, we want to be able to take a `BuildPlan`, and
102+update to a newer `BuildPlan` that keeps all packages at the same major
103+version. `updateBuildConstraints` turns a `BuildPlan` into a new
104+`BuildConstraints` with that restriction, and `updateBuildPlan` applies
105+`newBuildPlan` to that result. As mentioned previously: this is *not* a
106+validated result, and therefore `checkBuildPlan` must be used.
108+A `BuildPlan` can be acted on. This is done to check that all packages compile
109+together, run relevant test suites, test Haddock documentation is correct, and
110+produce as artifacts both a self-contained GHC binary package database and a
111+set of Haddock documentation. (Not yet implemented.)
113+A `BuildPlan` may be converted into a bundle to be uploaded to Stackage Server.
114+(Not yet implemented.)