Add: more content

1 files changed, 79 insertions, 0 deletions

diff --git a/patches.mdwn b/patches.mdwn
new file mode 100644
index 0000000..4f5b035
--- /dev/null
+++ b/patches.mdwn
@@ -0,0 +1,79 @@
+[[!meta title="Sending patches to vmdb2"]]
+
+vmdb2 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/
+[vmdb2]: http://git.liw.fi/vmdb2/
+[vmdb2.liw.fi]: http://git.liw.fi/vmdb2.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 [vmdb2][] and [vmdb2.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
+  liw@liw.fi. (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.
+
+
+# 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/