@@ -12,28 +12,32 @@ Packages in Stackage are not patched: all package changes occur upstream in Hack
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.
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.
15−To 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`.
15+To 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:
16−To add a set of packages, you would add:
18 "My Name <myemail@example.com> @mygithubuser":
17 "My Name <myemail@example.com> @mygithubuser":
19 - package1
18 - package1
20 - package2
19 - package2
21 - package3
20 - package3
23−Note that you should edit on the `master` branch (and not the `nightly` branch, which is used for the nightly docker builder image).
22+If your library depends on a C library, please add it to the `debian-bootstrap.sh` script.
25−After 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
24+After doing that commit with a message like "add foo-bar" and send a pull request.
26+The continuous integration job will do some checks to see if your package's dependencies are up-to-date.
28+The CI job notably doesn't compile packages, run tests, build documentation, or find missing C libraries.
29+If you want to be proactive or if CI fails, you can make sure that your package builds against the newest versions of all dependencies like this:
27−If you want to make sure that the package builds against the newest versions of all dependencies you can do this:
30$ ghc --version # Should be the same as the latest nightly, it's in the title of https://www.stackage.org/nightly
32$ ghc --version # Should be the same as the latest nightly, it's in the title of https://www.stackage.org/nightly
31$ cabal get PACKAGE
34$ cabal get PACKAGE
32$ cd PACKAGE-*
35$ cd PACKAGE-*
33$ cabal sandbox init # Should give "Creating a new sandbox" and not "Using an existing sandbox".
36$ cabal sandbox init # Should give "Creating a new sandbox" and not "Using an existing sandbox".
34$ cabal install --enable-tests --enable-benchmarks --dry-run | grep latest # Should give no results
37$ cabal install --enable-tests --enable-benchmarks --dry-run | grep latest # Should give no results
35$ cabal install --enable-tests --enable-benchmarks --allow-newer
38$ cabal install --enable-tests --enable-benchmarks --allow-newer
36$ cabal test
39$ cabal test
39**NB** Please use commit messages like "add foo-bar" or "add johndev's packages"
43**NB** Please use commit messages like "add foo-bar" or "add johndev's packages"
@@ -70,42 +74,70 @@ If a package's test suite is failing, the first job is to investigate why. If th
71## Following dependency upgrades
75## Following dependency upgrades
73−If 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.
77+If a new version of a dependency is released your package may fail to
78+build or tests may fail. In most cases we will add an upper bound on
79+the dependency so that your package remains in nightly. We'll also
80+create a github issue pinging you with the bounds issues or give build
81+logs showing failures. It's then up to you to modify your package.
75−If a package is not modified in a timely manner, it may be temporarily
83+We recommend that you also follow the dependencies of your packages on
76−removed from Stackage by the curator team, at which point it is your
84+[Packdeps](http://packdeps.haskellers.com/) (typically using the RSS
77−responsibility to add it back in via a new pull request. We typically
85+feeds) as well as that often gives you notice ahead of stackage
78−use fairly long windows on this, but at a minimum:
86+issues. There are cases where we will not notice a new release of a
87+package because of other upper bounds that are in place.
89+If a package is not updated in time, it may be temporarily removed
90+from Stackage by the curator team. We strive to notify you when this
91+happens. If it does you are always welcome to file another pull
92+request to add it back.
94+We typically use fairly long windows before disabling packages, but it
95+is decided on a case-by-case basis.
80−* If restrictive version bounds are the only problem, we will give at
97+* If restrictive version bounds are the only problem, we will give
81− least a week to respond.
98+ maintainers at least a week to respond.
82* If there are real breaking changes, the curator team will retain
99* If there are real breaking changes, the curator team will retain
83 more discretion on how long a window to give before dropping
100 more discretion on how long a window to give before dropping
84− packages. Historically, this has usually waited until the cutting of
101+ packages.
102+* We usually drop all upper bounds and disable packages when we create
85 a new Long Term Support (LTS) major version.
103 a new Long Term Support (LTS) major version.
104+* There are rare cases where an upper bound or build failure are hard
105+ to deal with so then we may disable
107+**NOTE** Previously we had stricter time limits, but we decided to
108+remove that: Anyone is free to add a package to Stackage regardless of
109+responsiveness guarantees. However, as stated above, we may elect to
110+temporarily remove a package if it is not updated in a timely manner.
87−**NOTE** Previously, this maintainer agreement put a time limit on
112+## Delays
88−maintainers, requiring a certain level of responsiveness for
89−modifications to be made. We have explicitly removed that: anyone is
90−free to add a package to Stackage regardless of responsiveness
91−guarantees. However, as stated above, we may elect to temporarily
92−remove a package if it is not updated in a timely manner.
94−## Failing to meet the time limits
114+Maintainers are humans, humans get sick/have babies/go on
115+holiday. Sometimes a dependency upgrade is extra time consuming.
96−Maintainers 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.
117+Consider finding a co-maintainer with access to SCM and Hackage to
98−The 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.
120+We appreciate if you notify us of any expected delays in the Github
121+issues, some kind soul might decide to help out.
100## Upgrading to a new GHC version
123## Upgrading to a new GHC version
125+The Stackage curation team tries to move Stackage Nightly to new
102−The 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:
126+versions of GHC quickly as they become available, while keeping LTS
127+Haskell on a regular release schedule. For package maintainers, the
128+most important impacts of a new GHC release are:
104−* 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
130+* We will typically do a sweep through the Stackage upper bounds and
131+ remove blocking packages. We prefer to do it this way rather than
132+ ask other maintainers to backport fixes.
105− * We will definitely do this at a GHC major version release, and may do so at a minor version release
133+ * We will definitely do this at a GHC major version release, and
134+ may do so at a minor version release
106−* Packages that are incompatible with the newest GHC version will be temporarily blocked
135+* Packages that are incompatible with the newest GHC version will be
136+ temporarily disabled
138+If your package ends up being temporarily disabled from Stackage
108−If 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.
139+Nightly, please simply send a pull request to add it back once it and
140+its dependencies are compatible with the newest GHC version.
110## Adding a package to an LTS snapshot
142## Adding a package to an LTS snapshot
@@ -119,8 +151,13 @@ If you would like to get your package added to an existing LTS Haskell major
119release (e.g., if `lts-8.9` is out, you would want your package to appear in
151release (e.g., if `lts-8.9` is out, you would want your package to appear in
120`lts-8.10`), please do the following in addition to the steps above:
152`lts-8.10`), please do the following in addition to the steps above:
154+* Check that your package can be built with that LTS major version (e.g. `stack build --test --bench --haddock --resolver lts-8.10`)
122* Open up a new issue on the [lts-haskell repo](https://github.com/fpco/lts-haskell/issues/new)
155* Open up a new issue on the [lts-haskell repo](https://github.com/fpco/lts-haskell/issues/new)
123−* Specify the LTS major version you would like your package to go into (e.g., lts-8)
156+ * Specify the LTS major versions you would like your packages to go into (e.g. lts-8)
124−* Provide a list of packages you would like added, and if relevant, any upper bounds on those packages
157+ * Provide a list of packages you would like added
158+ * If relevant, mention any upper bounds that are needed on those packages
159+* Be patient! The LTS releases are less frequent than Nightly. The
125−* Be patient! The LTS releases are less frequent than Nightly and by their nature more conservative, and therefore adding new packages is a more manual process. The Stackage curators will try to get to your issue as soon as possible, but it may take some time.
160+ Stackage curators will try to get to your issue as soon as possible,
126−* To add a package to more than one LTS version please file separate tickets for each major LTS release, since they will typically be built and added at different times.
161+ but it may take some time.
162+* We gradually stop maintainng old LTS major versions, so your
163+ request may take longer or be declined if it's for an old LTS.