-
Notifications
You must be signed in to change notification settings - Fork 808
Maintainers Agreement
This 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.
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.
Getting your package included in Stackage is simple:
- Create a fork on Github.
- Add your packages to Stackage.Config.
- Try to build; if this fails due to your packages, fix those failures.
- Once everything builds correctly, commit and send a pull request to this repo.
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.
Note: while it's highly encouraged that the actual package maintainer is also the Stackage maintainer, this is not necessary.
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:
-
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:
- A new package is still considered experimental, and therefore not suitable for inclusion in a stable set of packages.
- 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).
-
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.
- Michael Snoyman: Personally, I lean towards dropping upper bounds most of the time.
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.
- 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.
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.
When Stackage reports such a breakage, I see the following possible resolutions to the problem:
- Author uploads a fix.
- We put a version constraint in Stackage to use the previous known good version.
- Stackage itself applies a patch (dependent on issue #5).
- The package is dropped.
- 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.
Ultimately, I hope we have automated build machines and a centralized server to grab build reports. Until then, Stackage will work much more informally.