Skip to content

Latest commit

 

History

History
131 lines (95 loc) · 5.43 KB

CONTRIBUTING.md

File metadata and controls

131 lines (95 loc) · 5.43 KB
Raw

Contributing to xmonad and xmonad-contrib

Before Creating a GitHub Issue

New issue submissions should adhere to the following guidelines:

  • Does your issue have to do with xmonad, xmonad-contrib, or maybe even with the X11 library?

    Please submit your issue to the correct GitHub repository.

  • To help you figure out which repository to submit your issue to, and to help us resolve the problem you are having, create the smallest configuration file you can that reproduces the problem.

    You may find that the xmonad-testing repository is helpful in reproducing the problem with a smaller configuration file.

    Once you've done that please include the configuration file with your GitHub issue.

  • If possible, use the xmonad-testing repository to test your configuration with the bleeding-edge development version of xmonad and xmonad-contrib. We might have already fixed your problem.

Contributing Changes/Patches

Have a change to xmonad that you want included in the next release? Awesome! Here are a few things to keep in mind:

  • Review the above section about creating GitHub issues.

  • It's always best to talk with the community before making any nontrivial changes to xmonad. There are a couple of ways you can chat with us:

  • XMonad.Doc.Developing is a great resource to get an overview of xmonad. Make sure to also check it if you want more details on the coding style.

  • Continue reading this document!

Expediting Reviews and Merges

Here are some tips for getting your changes merged into xmonad:

  • If your changes can go into xmonad-contrib instead of xmonad, please do so. We rarely accept new features to xmonad. (Not that we don't accept changes to xmonad, just that we prefer changes to xmonad-contrib instead.)

  • Change the fewest files as possible. If it makes sense, submit a completely new module to xmonad-contrib.

  • Your changes should include relevant entries in the CHANGES.md file. Help us communicate changes to the community.

  • Make sure you test your changes against the most recent commit of xmonad (and xmonad-contrib, if you're contributing there). If you're adding a new module or functionality, make sure to add an example in the documentation and in the PR description.

  • Make sure you run the automated tests. Both xmonad-contrib and xmonad have test-suites that you could run with stack test for example.

  • When committing, try to follow existing practices. For more information on what good commit messages look like, see How to Write a Git Commit Message and the Kernel documentation about committing logical changes separately.

Style Guidelines

Below are some common style guidelines that all of the core modules follow. Before submitting a pull request, make sure that your code does as well!

  • Comment every top level function (particularly exported functions), and provide a type signature; use Haddock syntax in the comments.

  • Follow the coding style of the module that you are making changes to (n spaces for indentation, where to break long type signatures, …).

  • New code should not introduce any new warnings. If you want to check this yourself before submitting a pull request, there is the pedantic flag, which is enforced in our CI. You can enable it by building your changes with stack build --flag xmonad:pedantic or cabal build --flag pedantic.

  • Likewise, your code should be free of hlint warnings; this is also enforced in our GitHub CI.

  • Partial functions are to be avoided: the window manager should not crash, so do not call error or undefined.

  • Any pure function added to the core should have QuickCheck properties precisely defining its behavior.

  • New modules should identify the author, and be submitted under the same license as xmonad (BSD3 license).

Keep rocking!

xmonad is a passion project created and maintained by the community. We'd love for you to maintain your own contributed modules (approve changes from other contributors, review code, etc.). However, before we'd be comfortable adding you to the xmonad GitHub organization we need to trust that you have sufficient knowledge of Haskell and git; and have a way of chatting with you (IRC, Matrix, etc.).