git.iko.soy/typeable/servant
on prepare-0.19 help sign in
typeable/servant/CONTRIBUTING.md
115 lines 4.2 kB history raw
1# Contributing Guidelines
3Contributions are very welcome! To hack on the github version, clone the
4repository. You can use `cabal`:
6```shell
7./scripts/start-sandbox.sh # Initialize the sandbox and add-source the packages
8./scripts/test-all.sh # Run all the tests
9```
11Or `stack`:
13```shell
14stack setup # Downloads and installs a proper GHC version if necessary
15stack build --fast --pedantic # Install dependencies and build packages
16stack test # Run all the tests
17```
19Or `nix`:
20```shell
21./scripts/generate-nix-files.sh # Get up-to-date shell.nix files
22```
24To build the docs, see `doc/README.md`.
26## General
28Some things we like:
30- Explicit imports
31- Upper and lower bounds for packages
32- Few dependencies
33- -Werror-compatible (7.8, 7.10 and 8.0)
35Though we aren't sticklers for style, the `.stylish-haskell.yaml` and `HLint.hs`
36files in the repository provide a good baseline for consistency.
38**Important**: please do not modify the versions of the servant packages you are sending patches for.
40## Changelog entries
42We experiment with using [changelog-d tool](https://github.com/phadej/changelog-d) to assemble changelogs.
43You are not required to install it.
45In each PR please add a file to `changelog.d` directory named after issue you are solving or the pull request itself (in a separate commit after you know the pull request number). For example
47```cabal
48synopsis: One sentence summary of the change.
49prs: #1219
50issues: #1028
52description: {
54A longer description. Small changes don't need this.
55Bigger ones definitely do, for example we try to include migration hints
56for breaking changes.
58However if you don't know what to write, that's ok too.
60By the way, the braces around are omitted when the file is parsed.
61They can be used so the field doesn't need to be indented, which is handy
62for prose.
65```
67## PR process
69We try to give timely reviews to PRs that pass CI. If CI for your PR fails, we
70may close the PR if it has been open for too long (though you should feel free
71to reopen when the issues have been fixed).
73We require two +1 from the maintainers of the repo. If you feel like there has
74not been a timely response to a PR, you can ping the Maintainers group (with
75`@haskell-servant/maintainers`).
77## New combinators
79We encourage people to experiment with new combinators and instances - it is
80one of the most powerful ways of using `servant`, and a wonderful way of
81getting to know it better. If you do write a new combinator, we would love to
82know about it! Either hop on #servant on freenode and let us know, or open an
83issue with the `news` tag (which we will close when we read it).
85As for adding them to the main repo: maintaining combinators can be expensive,
86since official combinators must have instances for all classes (and new classes
87come along fairly frequently). We therefore have to be quite selective about
88those that we accept. If you're considering writing a new combinator, open an
89issue to discuss it first! Or contribute it to the
90[servant-contrib](https://github.com/haskell-servant/servant-contrib) repository.
91You could release your combinator as a separate package, of course.
94## New classes
96The main benefit of having a new class and package in the main servant repo is
97that we get to see via CI whether changes to other packages break the build.
98Open an issue to discuss whether a package should be added to the main repo. If
99we decide that it can, you can still keep maintainership over it.
101Whether or not you want your package to be in the repo, create an issue with
102the `news` label if you make a new package so we can know about it!
104## Release policy
106We are currently moving to a more aggressive release policy, so that you can get
107what you contribute from Hackage fairly soon. However, note that prior to major
108releases it may take some time in between releases.
110## Reporting security issues
112Please email haskell-servant-maintainers AT googlegroups DOT com. This group is
113private, and accessible only to known maintainers. We will then discuss how to
114proceed. Please do not make the issue public before we inform you that we have
115a patch ready.