From 2086eb0f142595a008279d8fd028d7cea9992227 Mon Sep 17 00:00:00 2001 From: Adam Bergmark Date: Tue, 16 Aug 2016 12:51:21 +0200 Subject: [PATCH 1/4] Clarify the addition of packages and building the package set. * Packdeps can be used to make sure a package supports the latest version of all its dependencies. * The all-cabal-files repository can be used to check if newly released packages have been synced. * People who want to make an os distribution of stackage may also want to build the entire package set. * Delete old text about the disabled docker image. --- MAINTAINERS.md | 12 +++++++----- README.md | 37 ++++++++----------------------------- 2 files changed, 15 insertions(+), 34 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index f0091d96..8c8ca954 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -3,7 +3,7 @@ This project is built around the concept of maintainers taking responsibility fo The idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. Specifically, we aim for: * All packages are buildable and testable from Hackage. We recommend [the Stack Travis script](http://docs.haskellstack.org/en/stable/GUIDE.html#travis-with-caching), 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 newest versions of all dependencies (You can verify this by checking http://packdeps.haskellers.com/feed?needle=PACKAGENAME). * 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)). ## Adding a package @@ -25,10 +25,12 @@ After doing that, send a pull request (with a commit message like "add foo-bar") (`build-constraints.yaml` is the most frequently changed file in this git repo so commit messages like "update build-constraints.yaml" are not helpful). -**NB2** There can be a delay of up to an hour before package versions newly -uploaded to Hackage appear to our build server. If you just uploaded a package -to Hackage that you're trying to get included, we recommend waiting an hour -before opening the PR. +**NB2** There can be a delay of up to an hour before package versions +newly uploaded to Hackage appear to our build server. If you just +uploaded a package to Hackage that you're trying to get included, we +recommend waiting an hour before opening the PR. You can also verify +this by making sure the latest version is listed in +https://github.com/commercialhaskell/all-cabal-files/tree/master/PACKAGENAME. ## Uploading a new package diff --git a/README.md b/README.md index 83ebb2f5..d2bdeb68 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ 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 Stack Travis script](http://docs.haskellstack.org/en/stable/GUIDE.html#travis-with-caching), which ensures a package is not accidentally incomplete. -* The package is compatible with the newest versions of all dependencies. +* The package is compatible with the newest versions of all dependencies (You can verify this by checking http://packdeps.haskellers.com/feed?needle=PACKAGENAME). * 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). @@ -57,34 +57,13 @@ flow](https://github.com/fpco/stackage/blob/master/DATA-FLOW.md). Build the package set --------------------- -Generally, building the package set should be done only by the Stackage build -machine by the Stackage curation team. If you're interested in trying this -yourself, please check out [the curator -guide](https://github.com/fpco/stackage/blob/master/CURATORS.md), though be -aware that this is not a recommended practice and there likely will be problems -you will need to debug yourself. - -### Docker - -Note: This method has been disabled for now, but may be enabled again in the future. - -If you'd like to check a build plan, or perform an entire build, without -specially configuring your system, Docker may be a good approach. To check if -some modifications to `build-constraints.yaml` are valid, try the following: - -1. Create a local clone of the `stackage` repo -2. Make modifications to your local `build-constraints.yaml` -3. Inside the `stackage` working directory, run the following: - - ``` - $ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage check' - ``` - -Similarly, if you'd like to perform an entire build, you can replace the last step with: - -``` -$ docker run -it --rm -v $(pwd):/stackage -w /stackage snoyberg/stackage /bin/bash -c 'cabal update && stackage nightly --skip-upload' -``` +Generally only the stackage build server run by the stackage curator +team and people intrested in incorporating stackage snapshots into an +OS distribution need to build the entire package set. If you're +interested in trying this yourself, please check out +[the curator guide](https://github.com/fpco/stackage/blob/master/CURATORS.md), +though be aware that this is not a recommended practice and there +likely will be problems you will need to debug yourself. ## Processing From 2334d6f1077f2ecc746295a4fbc52e422ef293e6 Mon Sep 17 00:00:00 2001 From: Adam Bergmark Date: Tue, 16 Aug 2016 13:01:17 +0200 Subject: [PATCH 2/4] CURATORS: Check packdeps before merging pull requests --- CURATORS.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/CURATORS.md b/CURATORS.md index 6925e3e9..d2fad636 100644 --- a/CURATORS.md +++ b/CURATORS.md @@ -21,9 +21,10 @@ process works: ## Pull requests -The typical story on pull requests is: if Travis accepts it, and the author -only added packages under his/her own name, merge it. If the build later fails -(see below), then block the package until it's fixed. +The typical story on pull requests is: If Travis accepts it, packdeps +says the package is up to date, and the author only added packages +under his/her own name, merge it. If the build later fails (see +below), then block the package until it's fixed. ## Fixing bounds issues From 404cd4b55bfc125fa041acb22c73e50d41484dca Mon Sep 17 00:00:00 2001 From: Adam Bergmark Date: Wed, 17 Aug 2016 13:34:40 +0200 Subject: [PATCH 3/4] Clarify that packdeps only finds restrictive upper bounds --- CURATORS.md | 10 ++++++---- MAINTAINERS.md | 2 +- README.md | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CURATORS.md b/CURATORS.md index d2fad636..8fbafd60 100644 --- a/CURATORS.md +++ b/CURATORS.md @@ -21,10 +21,12 @@ process works: ## Pull requests -The typical story on pull requests is: If Travis accepts it, packdeps -says the package is up to date, and the author only added packages -under his/her own name, merge it. If the build later fails (see -below), then block the package until it's fixed. +The typical story on pull requests is: If Travis accepts it and the +author only added packages under his/her own name, merge it. If the +build later fails (see below), then block the package until it's +fixed. + +Optionally we can check if packdeps says the package is up to date. ## Fixing bounds issues diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 8c8ca954..a47eb400 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -3,7 +3,7 @@ This project is built around the concept of maintainers taking responsibility fo The idea behind Stackage is that, if all packages work with the newest versions of dependencies, we avoid dependency hell. Specifically, we aim for: * All packages are buildable and testable from Hackage. We recommend [the Stack Travis script](http://docs.haskellstack.org/en/stable/GUIDE.html#travis-with-caching), which ensures a package is not accidentally incomplete. -* All packages are compatible with the newest versions of all dependencies (You can verify this by checking http://packdeps.haskellers.com/feed?needle=PACKAGENAME). +* 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). * 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)). ## Adding a package diff --git a/README.md b/README.md index d2bdeb68..9ad3259a 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ 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 Stack Travis script](http://docs.haskellstack.org/en/stable/GUIDE.html#travis-with-caching), which ensures a package is not accidentally incomplete. -* The package is compatible with the newest versions of all dependencies (You can verify this by checking http://packdeps.haskellers.com/feed?needle=PACKAGENAME). +* The package is compatible with the newest versions of all dependencies (You can find restrictive upper bounds by visiting http://packdeps.haskellers.com/feed?needle=PACKAGENAME). * 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). From 097b64503dda18920460b33a45604950e0d6fc0e Mon Sep 17 00:00:00 2001 From: Adam Bergmark Date: Wed, 17 Aug 2016 13:51:03 +0200 Subject: [PATCH 4/4] Add instructions for testing a package against the latest versions of dependencies --- MAINTAINERS.md | 16 ++++++++++++++-- README.md | 2 +- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index a47eb400..a98cce6f 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -21,6 +21,18 @@ To add a set of packages, you would add: 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 +If you want to make sure that the package builds against the newest versions of all dependecies you can do this: +``` +$ cabal update +$ ghc --version # Should give v8.0.1 +$ cabal get PACKAGE-VERSION # e.g. aeson-0.11.2.1 +$ cd PACKAGE-VERSION +$ cabal sandbox init # Should give "Creating a new sandbox" and not "Using an existing sandbox". +$ cabal install --enable-tests --enable-benchmarks --dry-run | grep latest # Should give no results +$ cabal install --enable-tests --enable-benchmarks --allow-newer +$ cabal test +``` + **NB** 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). @@ -28,8 +40,8 @@ so commit messages like "update build-constraints.yaml" are not helpful). **NB2** There can be a delay of up to an hour before package versions newly uploaded to Hackage appear to our build server. If you just uploaded a package to Hackage that you're trying to get included, we -recommend waiting an hour before opening the PR. You can also verify -this by making sure the latest version is listed in +recommend waiting an hour before opening the PR. You can verify this +by making sure the latest version is listed in https://github.com/commercialhaskell/all-cabal-files/tree/master/PACKAGENAME. diff --git a/README.md b/README.md index 9ad3259a..7fc1b93a 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ We welcome all packages, provided: * The package is compatible with the newest versions of all dependencies (You can find restrictive upper bounds by visiting http://packdeps.haskellers.com/feed?needle=PACKAGENAME). * 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). +Full details on how to add and test a package can be found in the [maintainers agreement](https://github.com/fpco/stackage/blob/master/MAINTAINERS.md#adding-a-package). __NOTE__: There is an approximate 30 minute delay between a package uploading to Hackage and being available to the Travis build script to check upper