vmdb2 → 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.

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.

An identical repository is hosted on gitlab for those who prefer the merge-request based workflow. GitLab is not entire free software, but "open core", and free software should use free tools.

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 link to that.

On patches (and pull requests and merge 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.