1# Instructions for Contributors
2
3To report bugs, please use the [GitHub issue tracker](https://github.com/haskell/containers/issues).
4We also appreciate [pull requests](https://github.com/haskell/containers/pulls) on GitHub.
5
6For proposing API changes or enhancements, please follow the [guidelines outlined on the Haskell Wiki](https://wiki.haskell.org/Library_submissions#Guide_to_proposers).
7All such changes should be discussed on the libraries@haskell.org mailing list.
8
9
10## Building, testing, and benchmarking
11
12Building, testing, and benchmarking the containers package can be done using either `cabal-install` or `stack`.
13
14### With cabal-install
15
16Minimum 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```
21cabal sandbox init
22cabal install --only-dependencies
23# Install test dependencies
24cabal 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
26cabal install 'criterion'
27# If you only need tests or benchmarks, you can omit the other --enable-xyz flag.
28cabal configure -v2 --enable-tests --enable-benchmarks
29cabal build
30cabal test
31cabal bench
32```
33
34
35### With [Stack](https://docs.haskellstack.org/en/stable/README/)
36
37Minimum stack version: 1.6.1
38
39```
40stack build
41stack test
42stack bench
43```
44
45
46## Troubleshooting
47
48- If you're using Stack, make sure you have version >= 1.6.1
49  ([stack#3624](https://github.com/commercialhaskell/stack/issues/3624),
50  [stack#3345](https://github.com/commercialhaskell/stack/issues/3345)).
51
52
53## Sending Pull Requests
54
55When 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
78The internal docs are generated using Haddock which can be invoked with `cabal
79haddock` or `stack haddock`.
80
81The external docs are served by ReadTheDocs at
82https://haskell-containers.readthedocs.io and live in the `docs/` directory. To
83build the docs locally run `pip install sphinx sphinx-autobuild` to install the
84dependencies, `git submodule update --init`, and then `cd docs/ && make html`.
85