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](http://docs.haskellstack.org/en/stable/GUIDE.html#travis-with-caching), 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://www.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, first fork this repository.
16In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file, there's a section called `packages`.
17To add a set of packages, you would add:
19 "My Name myemail@example.com @mygithubuser":
24After doing that, send a pull request (with a commit message like "add foo-bar"). We do not require new submissions to be tested against the rest of Stackage before the pull request (though it is a good idea to do so if you can with `stack --resolver nightly exec stackage-curator check` and `stack --resolver nightly build`), provided you meet the dependency version requirements above. If your library depends on a C library, add a note to your pull request with the Ubuntu library name, or even better edit the `debian-bootstrap.sh` script directly
26If you want to make sure that the package builds against the newest versions of all dependecies you can do this:
29$ ghc --version # Should give v8.0.2
30$ cabal get PACKAGE-VERSION # e.g. aeson-0.11.2.1
32$ cabal sandbox init # Should give "Creating a new sandbox" and not "Using an existing sandbox".
33$ cabal install --enable-tests --enable-benchmarks --dry-run | grep latest # Should give no results
34$ cabal install --enable-tests --enable-benchmarks --allow-newer
38**NB** Please use commit messages like "add foo-bar" or "add johndev's packages"
39(`build-constraints.yaml` is the most frequently changed file in this git repo
40so commit messages like "update build-constraints.yaml" are not helpful).
42**NB2** There can be a delay of up to an hour before package versions
43newly uploaded to Hackage appear to our build server. If you just
44uploaded a package to Hackage that you're trying to get included, we
45recommend waiting an hour before opening the PR. You can verify this
46by making sure the latest version is listed at
47https://github.com/commercialhaskell/all-cabal-metadata/tree/master/packages/.
49## Uploading a new package version
51When a new version of a package in Stackage is uploaded to Hackage, we automatically try to include it in Stackage (unless the new version is considered experimental). 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.
53If the new version doesn't compile then the package author should upload a fixed version.
55If 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.
58## Following dependency upgrades
60If a new version of a dependency is released, and that stops your package compiling/passing the tests, then it is your responsibility to modify your package. It is recommended that all package maintainers follow the dependencies of their packages on [Packdeps](http://packdeps.haskellers.com/), typically using the RSS feeds.
62If a package is not modified in a timely manner, it may be temporarily
63removed from Stackage by the curator team, at which point it is your
64responsibility to add it back in via a new pull request. We typically
65use fairly long windows on this, but at a minimum:
67* If restrictive version bounds are the only problem, we will give at
68 least a week to respond.
69* If there are real breaking changes, the curator team will retain
70 more discretion on how long a window to give before dropping
71 packages. Historically, this has usually waited until the cutting of
72 a new Long Term Support (LTS) major version.
74**NOTE** Previously, this maintainer agreement put a time limit on
75maintainers, requiring a certain level of responsiveness for
76modifications to be made. We have explicitly removed that: anyone is
77free to add a package to Stackage regardless of responsiveness
78guarantees. However, as stated above, we may elect to temporarily
79remove a package if it is not updated in a timely manner.
81## Failing to meet the time limits
83Maintainers are humans, humans get sick/have babies/go on holiday. If you have regular problems meeting the limits, find a co-maintainer. If you have a one-off problem, respond to the GitHub tickets saying so, and some kind soul might pick up the slack.
85The soft time limits are intended to prevent people being inconvenienced because of problems in other packages. Where such inconvenience happens, we will drop the offending packages from Stackage. While upper bounds are sometimes a temporary solution, they are against the ethos of Stackage, so will not be kept for longer periods.
87## Upgrading to a new GHC version
89The Stackage curation team tries to move Stackage Nightly to new versions of GHC quickly as they become available, while keeping LTS Haskell on a regular release schedule. For package maintainers, the most important impacts of a new GHC release are:
91* We will typically do a sweep through the Stackage upper bounds and aggressively remove packages that block them. This is because, in most cases, we will need to move to the newest versions of a package to get support for the latest GHC, and asking package maintainers to backport their fixes is an undue burden
92 * We will definitely do this at a GHC major version release, and may do so at a minor version release
93* Packages that are incompatible with the newest GHC version will be temporarily blocked
95If your package ends up being temporarily removed from Stackage Nightly, please simply send a pull request to add it back once it and its dependencies are compatible with the newest GHC version.
97## Adding a package to an LTS snapshot
99The steps above affect the Stackage Nightly builds, but do not directly affect
100LTS Haskell builds. When we build a new LTS Haskell major version (anything
101ending in `.0`), the package set is taken from Stackage Nightly. Therefore, by
102following the above steps, you can get your package into the next major LTS
105If you would like to get your package added to an existing LTS Haskell major
106release (e.g., if `lts-3.21` is out, you would want your package to appear in
107`lts-3.22`), please do the following in addition to the steps above:
109* Open up a new issue on the [lts-haskell repo](https://github.com/fpco/lts-haskell/issues/new)
110* Specify the LTS major version you would like your package to go into (e.g., lts-3)
111* Provide a list of packages you would like added, and if relevant, any upper bounds on those packages
112* Be patient! The LTS releases are by their nature more conservative than nightly, and therefore adding new packages is a more manual process. The Stackage curators will try to get to your issue quickly, but there may be some delay.
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