[[!meta title="Sending patches to ick or ick.liw.fi"]]

Ick is a free software project and has an associated website. This
page explains how you can contribute changes to either.

[git]: https://git-scm.com/
[git.liw.fi]: http://git.liw.fi/
[ick2]: http://git.liw.fi/ick2/
[ick.liw.fi]: http://git.liw.fi/ick.liw.fi
[Gitano]: https://www.gitano.org.uk/
[free software should use free tools]: https://mako.cc/writing/hill-free_tools.html

We use the [git][] version control system. Our repositories are hosted
on a [git.liw.fi][], a personal server hosted by Lars Wirzenius, using
the [Gitano][] software. See the [ick2][] and [ick.liw.fi][]
repositories.

We don't use GitHub, as it runs proprietary
software, and [free software should use free tools][]. We also don't
use one of the free software implementations that are similar to
GitHub, because we prefer Gitano, and some of us don't enjoy the
pull-request style of accepting contributions that GitHub has.
However, we're happy to get changes from GitHub, or any other git
server, over an open protocol.

Despite our aversion toward GitHub and pull requests, we want to make
it easy for you to send us patches.

Here's a few ways you can send us changes:

* Tell us in your own free words what the proposed change is, over
  e-mail or another medium. We can do the change in git ourselves, if
  we agree to the change. This is good for small changes, such as
  wording changes, or such.

  If you don't know how to use git, use this method. It's low tech,
  but also low friction to you, even if a little more work for us.

* Send us changes formatted with "git format-patch", over email to the
  ick-discuss mailing list. (Using "git send-email" is good, too.)

  If you're sending a patch series consisting of several patches,
  add a "cover letter" that explains what the whole series is about.

* Make the changes available on a different git server, and send us a
  URL we can pull from. You can use GitHub or any other server that's
  convenient for you. You can even create a pull request and send a
  URL to that. We prefer you send us the URL over e-mail to the
  ick-discuss mailing list, as that gets automatically tracked


# On patches (and pull requests)

We prefer a patch series and pull request to tell a story of the
change that is easy to follow and review and understand.

* Each patch/commit should have a clear commit message. The commit
  message should explain why the change is made, and not just rephrase
  the diff. The commit message should stand on its own, as it will be
  read on its own in the future, when someone is debugging the
  program, possibly with "git bisect".

* The commit message should follow the [this guide][], and
  additionally the first summary line should start with one of the
  words "Add", "Change", "Drop", or "Refactor".

* Each patch/commit should change only one logical thing at a time. It
  should also not be semantically large: avoid changing many parts of
  the code at once, unless it's trivial changes like renaming a class.
  Do such renames in a patch/commit that makes no other changes.

* Don't squash commits into one for a pull request.

* If necessary, clean up the branch/pull request with "git rebase -i"
  to produce something that's clear and easy to review.

* Remember to update the NEWS file for any changes visible to the user
  or system administrator.

[this guide]: https://chris.beams.io/posts/git-commit/