From f66981fc8a10a2db6cfb38ad3736619b824779f9 Mon Sep 17 00:00:00 2001 From: "Julian K. Arni" Date: Thu, 7 Jan 2016 00:53:17 +0100 Subject: [PATCH 1/3] First pass at CONTRIBUTING --- CONTRIBUTING.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 27 +----------------- 2 files changed, 77 insertions(+), 26 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..74577d3f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing Guidelines + +Contributions are very welcome! To hack on the github version, clone the +repository. You can use `cabal`: + +```shell +./scripts/start-sandbox.sh # Initialize the sandbox and add-source the packages +./scripts/test-all.sh # Run all the tests +``` + +`stack`: + +```shell +stack build # Install and build packages +stack test # Run all the tests +``` + +Or `nix`: +```shell +./scripts/generate-nix-files.sh # Get up-to-date shell.nix files +``` + + +## General + +Some things we like: + +- Explicit imports +- Upper and lower bounds for packages +- Few dependencies +- -Werror-compatible + +Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs` +files in the repository provide a good baseline for consistency. + +Please include a description of the changes in your PR in the `CHANGELOG.md` of +the packages you've changed. And of course, write tests! + +## PR process + +We require two +1 from the maintainers of the repo. If you feel like there has +not been a timely response to a PR, you can ping the Maintainers group (with +`@Maintainers`). + +## New combinators + +We encourage people to experiment with new combinators and instances - it is +one of the most powerful ways of using `servant`, and a wonderful way of +getting to know it better. If you do write a new combinator, we would love to +know about it! Either hop on #servant on freenode and let us know, or open an +issue with the `news` tag (which we will close when we read it). + +As for adding them to the main repo: maintaining combinators can be expensive, +since official combinators must have instances for all classes (and new classes +come along fairly frequently). We therefore have to be quite selective about +those that we accept. If you're considering writing a new combinator, open an +issue to discuss it first! + + +## New classes + +The main benefit of having a new class and package in the main servant repo is +that we get to see via CI whether changes to other packages break the build. +Open an issue to discuss whether a package should be added to the main repo. If +we decide that it can, you can still keep maintainership over it. + +Whether or not you want your package to be in the repo, create an issue with +the `news` label if you make a new package so we can know about it! + +## Release policy + +We are currently moving to a more aggresive release policy, so that you can get +what you contribute from Hackage fairly soon. However, note that prior to major +releases it may take some time in between releases. If you think you're change +is small enough that you should be backported to released major versions, say +so in the issue or PR. diff --git a/README.md b/README.md index 0f13f495..3cf786ea 100644 --- a/README.md +++ b/README.md @@ -17,29 +17,4 @@ list](https://groups.google.com/forum/#!forum/haskell-servant). ## Contributing -Contributions are very welcome! To hack on the github version, clone the -repository. You can use `cabal`: - -```shell -./scripts/start-sandbox.sh # Initialize the sandbox and add-source the packages -./scripts/test-all.sh # Run all the tests -``` - -`stack`: - -```shell -stack build # Install and build packages -stack test # Run all the tests -``` - -Or `nix`: -```shell -./scripts/generate-nix-files.sh # Get up-to-date shell.nix files -``` - -Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs` -files in the repository provide a good baseline for consistency. - -Please include a description of the changes in your PR in the `CHANGELOG.md` of -the packages you've changed. And of course, write tests! - +See `CONTRIBUTING.md` From 832f1b985ffa9278e1d7b1fad8f7cdc743058469 Mon Sep 17 00:00:00 2001 From: "Julian K. Arni" Date: Thu, 7 Jan 2016 13:05:13 +0100 Subject: [PATCH 2/3] Review fixes and note about CI. --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 74577d3f..0c76f11f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,7 +28,7 @@ Some things we like: - Explicit imports - Upper and lower bounds for packages - Few dependencies -- -Werror-compatible +- -Werror-compatible (for both 7.8 and 7.10) Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs` files in the repository provide a good baseline for consistency. @@ -38,6 +38,10 @@ the packages you've changed. And of course, write tests! ## PR process +We try to give timely reviews to PRs that pass CI. If CI for your PR fails, we +may close the PR if it has been open for too long (though you should feel free +to reopen when the issues have been fixed). + We require two +1 from the maintainers of the repo. If you feel like there has not been a timely response to a PR, you can ping the Maintainers group (with `@Maintainers`). @@ -53,7 +57,7 @@ issue with the `news` tag (which we will close when we read it). As for adding them to the main repo: maintaining combinators can be expensive, since official combinators must have instances for all classes (and new classes come along fairly frequently). We therefore have to be quite selective about -those that we accept. If you're considering writing a new combinator, open an +those that we accept. If your considering writing a new combinator, open an issue to discuss it first! @@ -72,5 +76,5 @@ the `news` label if you make a new package so we can know about it! We are currently moving to a more aggresive release policy, so that you can get what you contribute from Hackage fairly soon. However, note that prior to major releases it may take some time in between releases. If you think you're change -is small enough that you should be backported to released major versions, say +is small enough that it should be backported to released major versions, say so in the issue or PR. From 32612c903c844903651f4cc87d802f8b41a63dc5 Mon Sep 17 00:00:00 2001 From: "Julian K. Arni" Date: Thu, 7 Jan 2016 17:18:46 +0100 Subject: [PATCH 3/3] Review fixes --- CONTRIBUTING.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c76f11f..335f6094 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,8 +57,9 @@ issue with the `news` tag (which we will close when we read it). As for adding them to the main repo: maintaining combinators can be expensive, since official combinators must have instances for all classes (and new classes come along fairly frequently). We therefore have to be quite selective about -those that we accept. If your considering writing a new combinator, open an -issue to discuss it first! +those that we accept. If you're considering writing a new combinator, open an +issue to discuss it first! (You could release your combinator as a separate +package, of course.) ## New classes @@ -75,6 +76,4 @@ the `news` label if you make a new package so we can know about it! We are currently moving to a more aggresive release policy, so that you can get what you contribute from Hackage fairly soon. However, note that prior to major -releases it may take some time in between releases. If you think you're change -is small enough that it should be backported to released major versions, say -so in the issue or PR. +releases it may take some time in between releases.