From 5d33aa0122816ab8eaae95c0a8c49d3c75c42614 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 8 Sep 2018 13:05:17 +0300 Subject: Add: more content --- patches.mdwn | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 patches.mdwn (limited to 'patches.mdwn') 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/ -- cgit v1.2.1