MAINTAINERS.md · stackage

git.iko.soy/stackage

stackage/MAINTAINERS.md

222 lines 12 kB history raw

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](https://docs.haskellstack.org/en/stable/travis_ci/), 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.

11## Adding a package

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 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:

17 "My Name <myemail@example.com> @mygithubuser":

18 - package1

19 - package2

20 - package3

22If your library depends on a C library, please add it to the `debian-bootstrap.sh` script.

24After doing that commit with a message like "add foo-bar" and send a pull request.

26The continuous integration job will do some checks to see if your package's dependencies are up-to-date.

28The CI job notably doesn't compile packages, run tests, build documentation, or find missing C libraries.

29If you want to be proactive or if CI fails, you can make sure that your package builds against the latest nightly:

31```

32# Build from the tarball on Hackage to check for missing files

33$ stack unpack yourpackage && cd yourpackage-*

34# Generate a pristine stack.yaml, adding any missing extra-deps

35$ rm -f stack.yaml && stack init --resolver nightly --solver

36# Build, generate docs, test, and build benchmarks

37$ stack build --resolver nightly --haddock --test --bench --no-run-benchmarks

38```

40This approach works well, but has two limitations you should be aware

41of:

43* It won't notify you of restrictive upper bounds in your package if

44 Stackage has the same upper bounds. For that reason, we recommend

45 using [Packdeps](http://packdeps.haskellers.com/) (see "Following

46 dependency upgrades" below).

47* If the latest Stackage Nightly is missing some of the latest

48 packages, your build above may succeed whereas the Travis job may

49 fail. Again: Packdeps will help you detect this situation.

51Alternatively, you can build with `cabal`. Note that this may end up

52using older dependency versions:

54```

55$ ghc --version # Should be the same as the latest nightly, it's in the title of https://www.stackage.org/nightly

56$ cabal update

57$ cabal get PACKAGE

58$ cd PACKAGE-*

59$ cabal sandbox init # Should give "Creating a new sandbox" and not "Using an existing sandbox".

60$ cabal install --enable-tests --enable-benchmarks --dry-run | grep latest # Should give no results

61$ cabal install --enable-tests --enable-benchmarks --allow-newer

62$ cabal test

63$ cabal haddock

64```

66## Github and Notifications

68Stackage uses Github notifications to reduce overhead of contacting individual

69package maintainers through various channels. As a package maintainer, you will

70receive notifications for a number of reasons, package build failures of

71different sorts, blockages and bounds issues, etc.

73Please note, Github does some throttling on the number people that can be

74notified within one issue. This means that on issues created with a large

75number of packages affected, maintainers may not receive a notification. This

76is not ideal, but Stackage is largely a manual process and done on a best

77effort basis.

79## Uploading a new package version

81When a new version of a package in Stackage is uploaded to Hackage, we automatically try to include it in Stackage. 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.

83If the new version doesn't compile then the package author should upload a fixed version.

85If 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.

87## Following dependency upgrades

89If a new version of a dependency is released your package may fail to

90build or tests may fail. In most cases we will add an upper bound on

91the dependency so that your package remains in nightly. We'll also

92create a github issue pinging you with the bounds issues or give build

93logs showing failures. It's then up to you to modify your package.

95We recommend that you also follow the dependencies of your packages on

96[Packdeps](http://packdeps.haskellers.com/) (typically using the RSS

97feeds) as well as that often gives you notice ahead of stackage

98issues. There are cases where we will not notice a new release of a

99package because of other upper bounds that are in place.

100