11# Instructions for Contributors
22
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.
3+ To report bugs, or propose enchancements or changes, please use the
4+ [ GitHub issue tracker] ( https://github.com/haskell/containers/issues ) .
85
6+ You are also welcome to propose code changes in the form of
7+ [ pull requests] ( https://github.com/haskell/containers/pulls ) .
8+ A pull request will usually aim to fix an issue. Consider creating an issue for
9+ your change if one doesn't exist already.
910
1011## Building, testing, and benchmarking
1112
1213Building, testing, and benchmarking the containers package is done using ` cabal ` .
1314
14- To avoid recompiling the tests' other dependencies when making changes, you can
15- remove ` containers ` from the ` packages ` stanza of the ` cabal.project ` file.
16- Note: this will not work in the unlikely event that you are fixing a bug that
17- affects the test or benchmark framework itself. The ` Data.Set ` (for example)
18- used in the tests and benchmarks is compiled separately from the one exposed by
19- the ` containers ` package.
20- 2115### Procedure
2216
2317Minimum cabal version: 2.4
@@ -48,6 +42,10 @@ cabal run set-properties -- -p fromList
4842cabal test set-properties --test-options "-p fromList"
4943```
5044
45+ For quicker test and benchmark build times, remove ` containers ` from the
46+ ` packages ` stanza of the ` cabal.project ` file. This will avoid recompiling
47+ some test and benchmark dependencies that depend on ` containers ` .
48+ 5149#### For Windows users
5250
5351To compile ` containers-tests ` , you need symbolic links to be activated on git.
@@ -61,24 +59,27 @@ To do so on Windows 10 or higher, follow these steps:
6159
6260When you send a pull request, please:
6361
64- - Link to the libraries@haskell.org discussion thread if you are changing the
65- public API.
62+ - Mention the issue you are attempting to fix.
63+ 64+ - If your change adds new functionality or affects behaviour, please add
65+ QuickCheck properties exercising the code if they do not already exist. If you
66+ are fixing a bug that occurs too rarely for QuickCheck to hit reliably then
67+ consider adding unit tests as well.
6668
67- - If you are requesting a change that is likely to affect performance, we will
68- be able to evaluate it better if you include the results of running the
69- benchmarks before and after. If the current benchmarks cannot demonstrate
70- a desired difference, please try to add one or more new benchmarks to do so.
71- If there are significant changes, please include the benchmark results in
72- your commit message.
69+ - If your change is likely to affect performance, please share the results of
70+ running the benchmarks before and after. If the current benchmarks cannot
71+ demonstrate a desired difference, please try to add one or more new benchmarks
72+ to do so. If there are significant changes, please include the benchmark
73+ results in your commit message.
7374
74- - If you are requesting a change that adds new functionality or affects
75- behaviour, please add QuickCheck properties exercising the code if they
76- do not already exist. If you are fixing a bug that occurs too rarely for
77- QuickCheck to hit reliably then consider adding unit tests as well.
78- 79- - Update the change log for non-trivial changes.
75+ - When exporting a new definition, add a ` @since FIXME ` to the Haddocks for that
76+ definition. This is a [ @since annotation] ( https://haskell-haddock.readthedocs.io/latest/markup.html#since )
77+ that will be updated to the next version by a maintainer before releasing it.
8078
81- - Let us know how you wish to be credited in the changelog.
79+ - (Optional) Update the [ changelog] ( /containers/changelog.md ) for non-trivial
80+ changes. If you don't, a maintainer will do so before the next release. You
81+ may choose how you wish to be credited. We will mention your name on GitHub
82+ unless you specify otherwise.
8283
8384## Docs
8485
0 commit comments