Contributors Guide¶

Bug Reports¶

Please open an issue and use the provided template to include all necessary details.

The more detailed your report, the faster it can be resolved and will ensure it is resolved in the right way. Once your bug has been resolved, the responsible will tag the issue as Needs confirmation and assign the issue back to you. Once you have tested and confirmed that the issue is resolved, close the issue. If you are not a member of the project, you will be asked for confirmation and we will close it.

Documentation¶

If you would like to help with documentation, please note that for most cases the Wiki has been deprecated in favor of markdown files placed in a new /doc subdirectory of the repository itself. Please submit a pull request with your changes/additions.

The documentation is rendered on haskellstack.org by readthedocs.org using Sphinx and CommonMark. Since links and formatting vary from GFM, please check the documentation there before submitting a PR to fix those. In particular, links to other documentation files intentionally have .html extensions instead of .md, unfortunately (see #1506 for details).

If your changes move or rename files, or subsume Wiki content, please continue to leave a file/page in the old location temporarily, in addition to the new location. This will allow users time to update any shared links to the old location. Please also update any links in other files, or on the Wiki, to point to the new file location.

Code¶

If you would like to contribute code to fix a bug, add a new feature, or otherwise improve stack, pull requests are most welcome. It's a good idea to submit an issue to discuss the change before plowing into writing code.

If you'd like to help out but aren't sure what to work on, look for issues with the awaiting pr label. Issues that are suitable for newcomers to the codebase have the newcomer label. Best to post a comment to the issue before you start work, in case anyone has already started.

Please include a ChangeLog entry and documentation updates with your pull request.

Code Quality¶

The Stack projects uses HLint as a code quality tool.

Note that stack contributors need not dogmatically follow the suggested hints but are encouraged to debate their usefulness. If you find a hint is not useful and detracts from readability, consider marking it in the configuration file to be ignored. Please refer to the HLint manual for configuration syntax.

Quoting @mgsloan:

We are optimizing for code clarity, not code concision or what HLint thinks.

You can install HLint with stack. You might want to install it in the global project in case you run into dependency conflicts. HLint can report hints in your favourite text editor. Refer to the HLint repository for more details.

To install:

stack install hlint

Once installed, you can check your changes with:

hlint src/ test/ --cpp-simple --hint=HLint.hs

Where --cpp-simple strips # lines and --hint explicitly specifies the configuration file.