Drop support for pre-7.6 GHC
[packages/containers.git] / CONTRIBUTING.md
1 # Instructions for Contributors
2
3 To report bugs, please use the [GitHub issue tracker](https://github.com/haskell/containers/issues).
4 We also appreciate [pull requests](https://github.com/haskell/containers/pulls) on GitHub.
5
6 For proposing API changes or enhancements, please follow the [guidelines outlined on the Haskell Wiki](https://wiki.haskell.org/Library_submissions#Guide_to_proposers).
7 All such changes should be discussed on the libraries@haskell.org mailing list.
8
9
10 ## Building, testing, and benchmarking
11
12 Building, testing, and benchmarking the containers package can be done using either `cabal-install` or `stack`.
13
14 ### With cabal-install
15
16 Minimum cabal version: 1.24
17
18 _Note: The procedure here is a little weird because cabal configure is unable to solve for the constraints. We're looking into why that is ([#462](https://github.com/haskell/containers/issues/462))._
19
20 ```
21 cabal sandbox init
22 cabal install --only-dependencies
23 # Install test dependencies
24 cabal install 'test-framework >= 0.3.3' 'test-framework-quickcheck2 >= 0.2.9' 'QuickCheck >= 2.4.0.1' 'ChasingBottoms' 'HUnit' 'test-framework-hunit'
25 # Install benchmark dependencies
26 cabal install 'criterion'
27 # If you only need tests or benchmarks, you can omit the other --enable-xyz flag.
28 cabal configure -v2 --enable-tests --enable-benchmarks
29 cabal build
30 cabal test
31 cabal bench
32 ``` 
33
34
35 ### With [Stack](https://docs.haskellstack.org/en/stable/README/)
36
37 Minimum stack version: 1.6.1
38
39 ```
40 stack build
41 stack test
42 stack bench
43 ```
44
45
46 ## Troubleshooting
47
48 - If you're using Stack, make sure you have version >= 1.6.1
49   ([stack#3524](https://github.com/commercialhaskell/stack/issues/3624),
50   [stack#3345](https://github.com/commercialhaskell/stack/issues/3345)).
51
52
53 ## Sending Pull Requests
54
55 When you send a pull request, please:
56
57 - Link to the libraries@haskell.org discussion thread if you are changing the
58   public API.
59
60 - If you are requesting a change that is likely to affect performance, we will
61   be able to evaluate it better if you include the results of running the
62   benchmarks before and after. If the current benchmarks cannot demonstrate
63   a desired difference, please try to add one or more new benchmarks to do so.
64   If there are significant changes, please include the benchmark results in
65   your commit message.
66
67 - If you are requesting a change that adds new functionality or affects
68   behaviour, please add QuickCheck properties exercising the code if they
69   do not already exist. If you are fixing a bug that occurs too rarely for
70   QuickCheck to hit reliably then consider adding unit tests as well.
71   
72 - Update the change log for non-trivial changes.
73
74 - Let us know how you wish to be credited in the changelog.
75
76 ## Docs
77
78 The internal docs are generated using Haddock which can be invoked with `cabal
79 haddock` or `stack haddock`.
80
81 The external docs are served by ReadTheDocs at
82 https://haskell-containers.readthedocs.io and live in the `docs/` directory. To
83 build the docs locally run `pip install sphinx sphinx-autobuild` to install the
84 dependencies, `git submodule update --init`, and then `cd docs/ && make html`.