From 669eca71967bf6c1f513124a138e9620251a1792 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Thu, 26 Jul 2018 11:35:54 +0300 Subject: Add: page on submitting patches --- patches.mdwn | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 patches.mdwn (limited to 'patches.mdwn') 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/ -- cgit v1.2.1