@@ -105,6 +105,59 @@ remove that: Anyone is free to add a package to Stackage regardless of
105105responsiveness guarantees. However, as stated above, we may elect to
106106temporarily remove a package if it is not updated in a timely manner.
107107
108+## Understanding stackage issues
109+
110+### Bounds issues
111+
112+These are the most common.
113+
114+Using https://github.com/commercialhaskell/stackage/issues/6217 as an example.
115+
116+Our convention is to title a PR after the package that is being held
117+back from the nightly snapshot (here: aeson).
118+
119+The issue body is templated and looks like this:
120+
121+```
122+aeson-2.0.0.0 ([changelog](http://hackage.haskell.org/package/aeson-2.0.0.0/changelog)) (MAINTAINER) is out of bounds for:
123+- [ ] Agda-2.6.2 (>=1.1.2.0 && < 1.6). MAINTAINER. Used by: library
124+- [ ] HsYAML-aeson-0.2.0.0 (>=1.4.0.0 && < 1.6). MAINTAINER. Used by: library
125+- [ ] IPv6Addr-2.0.2 (>=0.8.0.2 && < 1.6). MAINTAINER. Used by: library
126+[...]
127+```
128+
129+This (usually - see "Other issues") means that there was a new release of the package in the
130+header (aeson). This is expected and the aeson maintainer is
131+not expected to act. They are pinged to notify them that the
132+latest version of their package will not be part of the nightly
133+snapshots until the issue closed.
134+
135+The list of packages with checkboxes denote the packages that prevent
136+us from using the latest version of aeson, the first version number is
137+the current version of that package in nightly (e.g. Agda 2.6.2). The
138+constraint in parenthesis `(>=1.1.2.0 && < 1.6)` is Agda's current
139+bound on `aeson`. To check this box we expect there to be an update
140+of Agda to support aeson 2.0.0.0.
141+
142+Once all boxes are checked we should be able to close the issue and
143+upgrade aeson.
144+
145+### Other issues
146+
147+Other common types of issues are
148+* Packages with failing tests, haddocks, or benchmarks (note that we only *compile* benchmarks)
149+ + Maintainers may choose to update these parts of their package, or
150+ to exclude them from the stackage build (e.g. adding a package to
151+ `skipped-tests`)
152+* New releases of packages that depend on packages that are not a part
153+ of stackage. This is denoted as `not present`
154+ + Maintainers are encouraged to ask the maintainer of these packages
155+ to join stackage, or to be the stackage contact person themselves.
156+* A new release of a package with stricter upper bounds than its previous version
157+ + This will look like a normal bounds issue, and should be treated
158+ the same way by maintainers. Curators usually resolve this by
159+ adding an upper bound to that package instead of its dependency.
160+
108161## Delays
109162
110163Maintainers are humans, humans get sick/have babies/go on