@@ -1,66 +1,51 @@
11This 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.
22
3−This Wiki page is meant to foster discussion of what such a social contract would look like, and ultimately come up with a solution that we can mostly agree upon.
3+The idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. Specifically, we aim for:
44
5−## Adding a package to Stackage
5+* All packages are buildable and testable from Hackage. We recommend [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis), which ensures a package is not accidentally incomplete.
6+* All packages are compatible with the newest versions of all dependencies.
7+* All packages are compatible with the versions of libraries that ship with GHC ([more information on lenient lower bounds](https://www.fpcomplete.com/blog/2014/05/lenient-lower-bounds)).
68
7−Getting your package included in Stackage is simple:
9+## Adding a package
810
9−* Create a fork on Github.
10−* Add your packages to [build-constraints.yaml](https://github.com/fpco/stackage/blob/master/build-constraints.yaml), following the format of other contributors.
11−* Commit and send a pull request.
11+Anyone can add a package to Stackage, but 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.
1212
13−Previously, we recommended trying to build the Stackage set yourself before sending a pull request. That's no longer necessary. Just send a pull request, and if there's a problem, the maintainer (currently: Michael Snoyman) will let you know.
13+To add your package, first fork this repository.
14+In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file, there's a section called `packages`.
15+To add a set of packages, you would add:
1416
15−Unlike the Haskell Platform, Stackage does not place quality requirements on packages. In theory, any package that compiles will be accepted to the Stackage package set. However, the maintainer must agree to follow the social contract spelled out in this document.
17+ "My Name myemail@example.com @mygithubuser":
18+ - package1
19+ - package2
20+ - package3
1621
17−Note: while it's highly encouraged that the actual package maintainer is also the Stackage maintainer, this is not necessary. You do not even need the package maintainer's approval to submit to Stackage, though it's a good idea to drop him/her a note.
22+After doing that, send a pull request. We do not require new submissions to be tested against the rest of Stackage before the pull request, provided you meet the dependency version requirements above.
1823
19−## Upper bounds
24+Please use commit messages like "add foo-bar" or "add johndev's packages"
25+(`build-constraints.yaml` is the most frequently changed file in this git repo
26+so commit messages like "update build-constraints.yaml" are not helpful).
2027
21−The main idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. As a result, upper bounds are considered a detriment. This plays out in two ways:
2228
23−1. By default, when a package is added to Stackage, it has no upper bound attached. Newer versions will be automatically included, assuming the newer versions compile and pass all tests. The only exceptions to this rule should be:
29+## Uploading a new package
2430
25− 1. A new package is still considered experimental, and therefore not suitable for inclusion in a stable set of packages.
26− 2. A package is a dependency of a large number of other packages and introduces a major breaking change. In this case, we'll temporarily impose an upper bound to give maintainers an upgrade grace period (see below).
31+When a new version of a package 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 raise GitHub issue tickets to resolve the issue.
2732
28−2. There's long been a debate about whether the PVP's requirement of putting upper bounds in a package is a good thing. We won't resolve that debate here, but Stackage *does* change the situation a bit. Since a package included in Stackage will be constantly compiled against newer versions of dependencies, breakages will be found quickly. Therefore, the motivation for upper bounds is lessened.
29− * Michael Snoyman: Personally, I lean towards dropping upper bounds most of the time.
33+If the new version doesn't compile then the package author should quickly (within 3 days) upload a fixed version.
3034
31−If you decide to put upper bounds on your packages in general in strict accordance with the PVP, your package may often times cause a Stackage build failure. In many cases, this can be resolved with a simple dependency version bump in your cabal file.
35+If 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.
3236
33−* Michael Snoyman: For these kinds of breakages, given the frequency with which they occur and the simplicity of solving them, I believe package maintainers should have 4 days to upload a new version to Hackage.
3437
35−It is highly recommended for all package maintainers to follow the dependencies of their packages on [Packdeps](http://packdeps.haskellers.com/). The site provides RSS feeds to simplify this process.
38+## Following dependency upgrades
3639
37−## Broken packages/broken tests
40+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 highly recommended that all package maintainers follow the dependencies of their packages on [Packdeps](http://packdeps.haskellers.com/), typically using the RSS feeds.
3841
39−It's bound to happen that broken packages will be uploaded to Hackage. In my experience, the most common situation is that a new version works for the developer on his/her OS/GHC version combination, but fails on other systems. Stackage is a great way to discover such a breakage.
42+**If restrictive version bounds are the only problem** then you must quickly (within 3 days) upload a new version with relaxed version bounds. Note that unlike the PVP, Stackage does not require or encourage upper bounds. Omitting upper bounds will mean you get fewer alerts for your package.
4043
41−When Stackage reports such a breakage, I see the following possible resolutions to the problem:
44+**If the new dependency causes breaking changes** then all package authors should quickly assess the likely impact on their package (within 3 days) and then produce a new compatible version. The expected timeline for new versions varies between 1 week and 1 month, depending on the significance of the change, and thus the work required to produce those new versions.
4245
43−1. Author uploads a fix.
44−2. We put a version constraint in Stackage to use the previous known good version.
45−3. Stackage itself applies a patch (dependent on [issue #5](https://github.com/fpco/stackage/issues/5)).
46−4. The package is dropped.
4746
48−* Michael Snoyman: My recommendation would be that we give the maintainer 24 hours to respond to the failure report. If there's no response in 24 hours, we put in a temporary version constraint. If this version constraint begins to cause problems for other packages in Stackage, and the maintainer is still non-responsive, we drop the package.
47+## Failing to meet the time limits
4948
50−If 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 simply not run the test suite.
49+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.
5150
52−One example is that, at the time of writing, the HTTP package test suite is not run. This is because the version of HTTP included with the Haskell Platform requires an older version of Warp. Since we cannot upgrade HTTP without breaking Haskell Platform compliance, we are required to simply omit the test suite.
53−
54−## Major breaking changes
55−
56−Many times, when a new major version of a library is released, the resulting breakage is trivial to address. Some examples of this were the transformers 0.2 to 0.3 migration, or text 0.10 to 0.11.
57−
58−* Michael Snoyman: In such cases, I believe maintainers should be given a one week grace period to update their packages, during which time the dependency is given an upper bound.
59−
60−Other times, breakage is much more significant. Obviously, the distinction between these two cases in entirely subjective, and must be left in the hands of the Stackage organizers.
61−
62−* Michael Snoyman: In the major breaking changes case, I believe a period of one month should be given for upgrades.
63−
64−## Automation
65−
66−Ultimately, I hope we have automated build machines and a centralized server to grab build reports. Until then, Stackage will work much more informally.
51+The time limits are intended to stop 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 long.