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.

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.