mirror of
https://github.com/commercialhaskell/stackage.git
synced 2026-01-11 23:08:30 +01:00
Rewrite the readme and maintainers agreement, shorter, simpler, encodes existing practice slightly better
This commit is contained in:
Neil Mitchell
parent
bc3cc0bbb6
commit
8a2209a0c0
@ -1,66 +1,51 @@
|
||||
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.
|
||||
The idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. Specifically, we aim for:
|
||||
|
||||
## Adding a package to Stackage
|
||||
* 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.
|
||||
* All packages are compatible with the newest versions of all dependencies.
|
||||
* 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)).
|
||||
|
||||
Getting your package included in Stackage is simple:
|
||||
## Adding a package
|
||||
|
||||
* Create a fork on Github.
|
||||
* Add your packages to [build-constraints.yaml](https://github.com/fpco/stackage/blob/master/build-constraints.yaml), following the format of other contributors.
|
||||
* Commit and send a pull request.
|
||||
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.
|
||||
|
||||
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.
|
||||
To add your package, first fork this repository.
|
||||
In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file, there's a section called `packages`.
|
||||
To add a set of packages, you would add:
|
||||
|
||||
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.
|
||||
"My Name myemail@example.com @mygithubuser":
|
||||
- package1
|
||||
- package2
|
||||
- package3
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Upper bounds
|
||||
Please use commit messages like "add foo-bar" or "add johndev's packages"
|
||||
(`build-constraints.yaml` is the most frequently changed file in this git repo
|
||||
so commit messages like "update build-constraints.yaml" are not helpful).
|
||||
|
||||
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:
|
||||
|
||||
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:
|
||||
## Uploading a new package
|
||||
|
||||
1. A new package is still considered experimental, and therefore not suitable for inclusion in a stable set of packages.
|
||||
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).
|
||||
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.
|
||||
|
||||
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.
|
||||
* Michael Snoyman: Personally, I lean towards dropping upper bounds most of the time.
|
||||
If the new version doesn't compile then the package author should quickly (within 3 days) upload a fixed version.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
* 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 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.
|
||||
## Following dependency upgrades
|
||||
|
||||
## Broken packages/broken tests
|
||||
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.
|
||||
|
||||
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.
|
||||
**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.
|
||||
|
||||
When Stackage reports such a breakage, I see the following possible resolutions to the problem:
|
||||
**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.
|
||||
|
||||
1. Author uploads a fix.
|
||||
2. We put a version constraint in Stackage to use the previous known good version.
|
||||
3. Stackage itself applies a patch (dependent on [issue #5](https://github.com/fpco/stackage/issues/5)).
|
||||
4. 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.
|
||||
## Failing to meet the time limits
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Major breaking changes
|
||||
|
||||
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.
|
||||
|
||||
* 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.
|
||||
|
||||
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.
|
||||
|
||||
* Michael Snoyman: In the major breaking changes case, I believe a period of one month should be given for upgrades.
|
||||
|
||||
## Automation
|
||||
|
||||
Ultimately, I hope we have automated build machines and a centralized server to grab build reports. Until then, Stackage will work much more informally.
|
||||
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.
|
||||
|
||||
73
README.md
73
README.md
@ -4,10 +4,27 @@ stackage
|
||||
[](https://travis-ci.org/fpco/stackage)
|
||||
|
||||
"Stable Hackage": creating a vetted set of packages from Hackage.
|
||||
This repository is for package authors and maintainers to get their packages into Stackage.
|
||||
If you simply want to use Stackage as an end user, please follow the instructions on [http://www.stackage.org/](http://www.stackage.org).
|
||||
|
||||
__NOTE__ This repository is for package authors and maintainers to get their packages into
|
||||
Stackage. If you simply want to use Stackage as an end user, please follow the
|
||||
instructions on [http://www.stackage.org/](http://www.stackage.org).
|
||||
We strongly recommend using the Haskell tool stack for doing builds, which
|
||||
includes built-in Stackage support: [stack](https://github.com/commercialhaskell/stack) [](https://travis-ci.org/commercialhaskell/stack).
|
||||
|
||||
|
||||
Add your package
|
||||
----------------
|
||||
|
||||
We welcome all packages, provided:
|
||||
|
||||
* The package author/maintainer agrees to the [maintainers agreement](https://github.com/fpco/stackage/blob/master/MAINTAINERS.md).
|
||||
* The package is buildable and testable from Hackage. We recommend the [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis), which ensures the package is not accidentally incomplete.
|
||||
* The package is compatible with the newest versions of all dependencies.
|
||||
* The package is 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)).
|
||||
|
||||
Full details on how to add a package can be found in the [maintainers agreement](https://github.com/fpco/stackage/blob/master/MAINTAINERS.md#adding-a-package).
|
||||
|
||||
Other repos
|
||||
-----------
|
||||
|
||||
The Stackage project consists of multiple repositories. This repository
|
||||
contains the metadata on packages to be included in future builds and some
|
||||
@ -19,11 +36,6 @@ project information. In addition, we have the following repositories:
|
||||
* [lts-haskell](https://github.com/fpco/lts-haskell)
|
||||
* [stackage-nightly](https://github.com/fpco/stackage-nightly)
|
||||
|
||||
We strongly recommend using the Haskell tool stack for doing builds, which
|
||||
includes built-in Stackage support:
|
||||
|
||||
* [stack](https://github.com/commercialhaskell/stack) [](https://travis-ci.org/commercialhaskell/stack)
|
||||
|
||||
We also support some add-on tools to cabal-install to make its usage with
|
||||
Stackage both easier and more secure:
|
||||
|
||||
@ -33,51 +45,6 @@ Stackage both easier and more secure:
|
||||
* [stackage-install](https://github.com/fpco/stackage-install) [](https://travis-ci.org/fpco/stackage-install)
|
||||
* [stackage-build-plan](https://github.com/fpco/stackage-build-plan) [](https://travis-ci.org/fpco/stackage-build-plan)
|
||||
|
||||
Get your package included
|
||||
-------------------------
|
||||
|
||||
In order to get your package included in the set of stable packages, you should
|
||||
send a pull request against this repository. In the [`build-constraints.yaml`](https://github.com/fpco/stackage/blob/master/build-constraints.yaml) file,
|
||||
there's a section called `packages`. In general, to add a set of
|
||||
packages, you would add:
|
||||
|
||||
"My Name myemail@example.com @mygithubuser":
|
||||
- package1
|
||||
- package2
|
||||
- package3
|
||||
|
||||
You can follow the examples of the other sets of packages in that function.
|
||||
Once you've done this, you can send a pull request to get your package
|
||||
included.
|
||||
|
||||
__NOTE__: In order to ease the process of adding new packages, we no longer
|
||||
require new submissions to be tested on your own system before sending a pull
|
||||
request. If you believe your package works with the newest versions of all
|
||||
dependencies, you may send a pull request without testing first.
|
||||
|
||||
Please use commit messages like "add foo-bar" or "add johndev's packages"
|
||||
(`build-constraints.yaml` is the most frequently changed file in this git repo
|
||||
so commit messages like "update build-constraints.yaml" are not helpful).
|
||||
|
||||
You should also read the [maintainers
|
||||
agreement](https://github.com/fpco/stackage/blob/master/MAINTAINERS.md).
|
||||
|
||||
Package Author Guidelines
|
||||
-------------------------
|
||||
|
||||
There are some basic rules to get your package to play nice with Stackage. Here
|
||||
are some quick guidelines to hopefully make this easier:
|
||||
|
||||
* Make sure that your code is buildability and testable from Hackage. Often
|
||||
times, authors test their builds locally, but the tarball that gets uploaded
|
||||
to Hackage is missing some necessary files. The best way to do this is to
|
||||
set up a Travis job to do it for you. We recommend the
|
||||
[multi-ghc-travis](https://github.com/hvr/multi-ghc-travis) approach.
|
||||
* Make your code compatible with the newest versions of all dependencies.
|
||||
* Make your code 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)).
|
||||
|
||||
There are certainly many other tips that could be added here. If you think of
|
||||
any, please send a pull request!
|
||||
|
||||
Build the package set
|
||||
---------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user