1This project is built around the concept of maintainers taking responsibility for making their packages work with the rest of the stable ecosystem, usually meaning the newest version of all dependencies. This is a social contract, and is not reflected in the codebase in any way.
3The idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. Specifically, we aim for:
5* All packages are buildable and testable from Hackage. We recommend [the Stack Travis script](https://docs.haskellstack.org/en/stable/travis_ci/), which ensures a package is not accidentally incomplete.
6* All packages are compatible with the newest versions of all dependencies (You can find restrictive upper bounds by visiting http://packdeps.haskellers.com/feed?needle=PACKAGENAME).
7* All packages in a snapshot are compatible with the versions of libraries that ship with the GHC used in the snapshot ([more information on lenient lower bounds](https://tech.fpcomplete.com/blog/2014/05/lenient-lower-bounds)).
9Packages in Stackage are not patched: all package changes occur upstream in Hackage.
13Anyone can add any package to Stackage but you may only add packages under your own name. It's highly encouraged that the actual package maintainer is also the Stackage maintainer, if that is not the case you should drop the package maintainer a note first.
15To add your package you can edit [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) directly on github or fork the project. There's a section called `packages` where you would add yourself and your packages:
17 "My Name <myemail@example.com> @mygithubuser":
22Any dependencies of your packages that are not already part of
23stackage also need to be added explicitly (When this happens you will
24see `not present` errors in the CI log). As mentioned above: If you
25don't maintain this package yourself it is preferable that the actual
26maintainer is also the stackage maintainer, but you are allowed to add
27it under your own name.
29If your package depends on a C library, please add it to the `debian-bootstrap.sh` script.
31After doing that, commit with a message like "add foo-bar" and send a pull request.
33The continuous integration job will do some checks to see if your package's dependencies are up-to-date.
35The CI job notably doesn't compile packages, run tests, build documentation, or find missing C libraries.
36If you want to be proactive or if CI fails, you can make sure that your package builds against the latest nightly.
37See the [verify-package](https://github.com/commercialhaskell/stackage/blob/master/verify-package) script in this repository.
39This approach works well, but has two limitations you should be aware
42* It won't notify you of restrictive upper bounds in your package if
43 Stackage has the same upper bounds. For that reason, we recommend
44 using [Packdeps](http://packdeps.haskellers.com/) (see "Following
45 dependency upgrades" below). You can also run `cabal outdated`.
46* If the latest Stackage Nightly is missing some of the latest
47 packages, your build above may succeed whereas the Travis job may
48 fail. Again: Packdeps will help you detect this situation.
50## Github and Notifications
52Stackage uses Github notifications to reduce overhead of contacting individual
53package maintainers through various channels. As a package maintainer, you will
54receive notifications for a number of reasons, package build failures of
55different sorts, blockages and bounds issues, etc.
57Please note, Github does some throttling on the number people that can be
58notified within one issue. This means that on issues created with a large
59number of packages affected, maintainers may not receive a notification. This
60is not ideal, but Stackage is largely a manual process and done on a best
63## Uploading a new package version
65When a new version of a package in Stackage is uploaded to Hackage, we automatically try to include it in Stackage. That can result in a number of possible failures. If there is a failure we temporarily introduce an upper bound, and open a GitHub issue ticket to resolve the issue.
67If the new version doesn't compile then the package author should upload a fixed version.
69If a package's test suite is failing, the first job is to investigate why. If this is due to a bad interaction with versions of other packages in Stackage, then it is the responsibility of the maintainer to fix the test suite. In some situations, it is acceptable to not run the test suite.
71## Following dependency upgrades
73If a new version of a dependency is released your package may fail to
74build or tests may fail. In most cases we will add an upper bound on
75the dependency so that your package remains in nightly. We'll also
76create a github issue pinging you with the bounds issues or give build
77logs showing failures. It's then up to you to modify your package.
79We recommend that you also follow the dependencies of your packages on
80[Packdeps](http://packdeps.haskellers.com/) (typically using the RSS
81feeds) as well as that often gives you notice ahead of stackage
82issues. There are cases where we will not notice a new release of a
83package because of other upper bounds that are in place.
85If a package is not updated in time, it may be temporarily removed
86from Stackage by the curator team. We strive to notify you when this
87happens. If it does you are always welcome to file another pull
88request to add it back.
90We typically use fairly long windows before disabling packages, but it
91is decided on a case-by-case basis.
93* If restrictive version bounds are the only problem, we will give
94 maintainers at least a week to respond.
95* If there are real breaking changes, the curator team will retain
96 more discretion on how long a window to give before dropping
98* We typically drop upper bounds and disable conflicting packages in Nightly after we create
99 a new Long Term Support (LTS) major version.
100* There are rare cases where an upper bound or build failure are hard
101 to deal with so then we may disable
103**NOTE** Previously we had stricter time limits, but we decided to
104remove that: Anyone is free to add a package to Stackage regardless of
105responsiveness guarantees. However, as stated above, we may elect to
106temporarily remove a package if it is not updated in a timely manner.
108## Understanding stackage issues
112These are the most common.
114Using https://github.com/commercialhaskell/stackage/issues/6217 as an example.
116Our convention is to title a PR after the package that is being held
117back from the nightly snapshot (here: aeson).
119The issue body is templated and looks like this:
122aeson-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
129This (usually - see "Other issues") means that there was a new release of the package in the
130header (aeson). This is expected and the aeson maintainer is
131not expected to act. They are pinged to notify them that the
132latest version of their package will not be part of the nightly
133snapshots until the issue closed.
135The list of packages with checkboxes denote the packages that prevent
136us from using the latest version of aeson, the first version number is
137the current version of that package in nightly (e.g. Agda 2.6.2). The
138constraint in parenthesis `(>=1.1.2.0 && < 1.6)` is Agda's current
139bound on `aeson`. To check this box we expect there to be an update
140of Agda to support aeson 2.0.0.0.
142Once all boxes are checked we should be able to close the issue and
147Other 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
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.
163Maintainers are humans, humans get sick/have babies/go on
164holiday. Sometimes a dependency upgrade is extra time consuming.
166Consider finding a co-maintainer with access to SCM and Hackage to
169We appreciate if you notify us of any expected delays in the Github
170issues, some kind soul might decide to help out.
172## Upgrading to a new GHC version
174The Stackage curation team tries to move Stackage Nightly to new
175versions of GHC quickly as they become available, while keeping LTS
176Haskell on a regular release schedule. For package maintainers, the
177most important impacts of a new GHC release are:
179* We will typically do a sweep through the Stackage upper bounds and
180 remove blocking packages. We prefer to do it this way rather than
181 ask other maintainers to backport fixes.
182 * We will definitely do this at a GHC major version release, and
183 may do so at a minor version release
184* Packages that are incompatible with the newest GHC version will be
187If your package ends up being temporarily disabled from Stackage
188Nightly, please simply send a pull request to add it back once it and
189its dependencies are compatible with the newest GHC version.
191Note that it is _not_ a goal of LTS Haskell to track the latest
192version of GHC. If you want the latest and greatest, Stackage Nightly
193is your best bet. In particular, LTS Haskell will often—but not
194always—avoid upgrading to the first point release of GHC
195releases (e.g., 8.x.1) to allow further testing and to get the
196benefits of the first bugfix release (e.g., 8.x.2).
198## Adding a package to an LTS snapshot
200The steps above affect the Stackage Nightly builds, but do not directly affect
201LTS Haskell builds. When we build a new LTS Haskell major version (anything
202ending in `.0`), the package set is taken from Stackage Nightly. Therefore, by
203following the above steps, you can get your package into the next major LTS
206If you would like to get your package added to the current LTS Haskell
207major release, please do the following in addition to the steps for Nightly described earlier:
209* Check that your package can be built with the current LTS version (e.g. `stack build --test --bench --haddock --resolver lts`)
210* Open up a new issue on the [lts-haskell repo](https://github.com/fpco/lts-haskell/issues/new)
211 * Provide a list of packages you would like added
212 * If relevant, mention any upper bounds that are needed on those packages
213* Be patient! The LTS releases are less frequent than Nightly. The
214 Stackage curators will try to get to your issue as soon as possible,
215 but it may take some time.
217## LTS package guarantees and exceptions
219In general, we try to stick to some rules when it comes to the
220packages included in LTS minor bumps. In particular:
222* If a package exists in LTS-X.Y, it should also exist in LTS-X.(Y+1)
223* We should not include a major version bump of a package between
224 LTS-X.Y and LTS-X.(Y+1)
226However, there are some cases where exceptions may be made, based
227purely on Stackage Curator discretion. The most common examples are:
229* If a package does not follow the PVP in its version number policy,
230 applying the standard version bump rules would not necessarily
231 makes sense. As an example, suppose package `foo` decides to
232 follow SemVer instead of the PVP. By our standard rules of version
233 bumps, a change from `foo-1.2.0` to `foo-1.3.0` would be
234 considered a major version bump, and disallowed in an LTS minor
235 version bump. However, if a package is following SemVer, this
236 would not be a breaking change, and curators may elect to include
237 it. Note though that curators and their tooling will not know your
238 package is following SemVer, so in this case you would have to open
239 an issue on the [lts-haskell repo](https://github.com/fpco/lts-haskell/issues/new).
241* If a package has overly restrictive version bounds on a
242 dependency, in particular constraining a minor version
243 unnecessarily, we may drop that package instead of artificially
244 holding back the dependency. As an example: suppose `LTS-20.1`
245 includes `foo-1.2.0` and `bar-1`. `bar-1` has a dependency `foo >=
246 1.2.0 && < 1.2.1`, which is overly constrained on the minor
247 version number according to the PVP. Then `foo-1.2.1` is
248 released. The Stackage Curator team would have two choices:
250 * Reject `foo-1.2.1` from `LTS-20.2`, since that is what `bar-1`
252 * Drop `bar-1` from `LTS-20.2`, and allow `foo-1.2.1`.
254 Decisions will need to be taken on a case-by-case basis, and may
255 depend on such issues as whether an important bugfix or security
256 update in included. The curator team may also try to notify the
257 author of `bar` to try and get a patched version released.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list