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