mirror of
https://github.com/xmonad/xmonad.git
synced 2025-05-19 00:20:22 -07:00
132 lines
5.4 KiB
Markdown
132 lines
5.4 KiB
Markdown
# 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:
|
|
|
|
- Join the [`#xmonad` IRC channel] on `irc.libera.chat` or the
|
|
official [matrix channel], which is linked to IRC. This is the
|
|
preferred (and fastest!) way to get into contact with us.
|
|
|
|
- Post a message to the [mailing list][ml].
|
|
|
|
* [XMonad.Doc.Developing][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][commit-cbeams] and the [Kernel
|
|
documentation][commit-kernel] 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][xmonad-gh-org] we need to trust that you have sufficient
|
|
knowledge of Haskell and git; and have a way of chatting with you ([IRC,
|
|
Matrix, etc.][community]).
|
|
|
|
[hlint]: https://github.com/ndmitchell/hlint
|
|
[xmonad]: https://github.com/xmonad/xmonad
|
|
[xmonad-contrib]: https://github.com/xmonad/xmonad-contrib
|
|
[xmonad-testing]: https://github.com/xmonad/xmonad-testing
|
|
[x11]: https://github.com/xmonad/X11
|
|
[ml]: https://mail.haskell.org/cgi-bin/mailman/listinfo/xmonad
|
|
[xmonad-doc-developing]: https://xmonad.github.io/xmonad-docs/xmonad-contrib/XMonad-Doc-Developing.html
|
|
[`#xmonad` IRC channel]: https://web.libera.chat/#xmonad
|
|
[matrix channel]: https://matrix.to/#/#xmonad:matrix.org
|
|
[commit-cbeams]: https://cbea.ms/git-commit/
|
|
[commit-kernel]: https://www.kernel.org/doc/html/v4.10/process/submitting-patches.html#separate-your-changes
|
|
[community]: https://xmonad.org/community.html
|
|
[xmonad-gh-org]: https://github.com/xmonad
|