Add: page on submitting patches

1 files changed, 92 insertions, 0 deletions

diff --git a/patches.mdwn b/patches.mdwn
new file mode 100644
index 0000000..579a2e4
--- /dev/null
+++ b/patches.mdwn
@@ -0,0 +1,92 @@
+[[!meta title="Sending patches to ick or ick.liw.fi"]]
+
+THIS IS A DRAFT
+
+    * Justify not using a PR-style approach?
+    * Send URL to a git repo I can pull from, or patches via email to
+      ick-discuss (git format-patch).
+    * List what repos I have on git.liw.fi for ick.
+    * Guidelines for what a changeset should include: ./check MUST
+      pass, NEWS SHOULD be updated, the patch series should "tell a
+      story" and should avoid mixing many changes, each patch should
+      be a logical step in the story of making a bigger change, avoid
+      large patches, since those are harder to review and understand
+
+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/
+[icks]: 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 [icks][] 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 expolains 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-dicusss 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 repharse
+  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/