[[!meta title="vmdb2 documentation"]] The vmdb2 manual is published at: * (HTML) * (PDF) # Getting vmdb2 to change so you can do what you want to do Sometimes it happens you want to do something that vmdb2 can't quite do. Here's some advice on what to do in that case, and what to avoid doing. * First of all, please realise that vmdb2 is a hobby project for me. I do it because it's fun, and it fulfils a need I personally have. One way my hobby projects are fun for me is when other people also find them useful, so I am usually happy to consider changes to make them more useful for others. However, I want to have fun while that happens. I also tend to be busy, and vmdb2 is hardly the only thing I do in my free time. All of this means that a change is more likely to happen if you make it easy for me. If I don't have fun, I can just go do something else. * Since I often don't have time for vmdb2 for days or even weeks at a time (remember, I have many other things to do), it's best to communicate over the issue tracker, instead of IRC or other chat systems, or private email. Discussions on the issue tracker are public and persistent, which means others will benefit from them, and can also join the discussion. IRC is ephemeral and only visible to whoever happens to be on the channel at the time. I'm also often forgetful, and having to search past IRC discussions (if I even still have them in my backlog) to remind myself what we've talked about previously, and any important details in those discussions, is both time-consuming and remarkably not fun. * If you need vmdb2 to add new functionality to achieve the thing you want to do, please always, always start by describing what the actual goal or need is. The "use case", in other words. Explain this without involving vmdb2. Do say "I want to create an image that boots on a Raspberry Pi". Don't say "add a plugin to use qemu-debootstrap". I don't like to guess what the purpose of a change is, and I don't want to make changes I don't understand. The use case can and should eventually become part of vmdb2's documentation. * I want to hear what the actual underlying need or want or goal is also for motivational reasons. I'm not an automaton that cranks out commits based on instructions from people on the Internet. I don't get paid to work on vmdb2. However, I do enjoy knowing "people are using my program to get Debian onto their Garbleplex development boards". * Also, as the maintainer of vmdb2, I need to consider all use cases and the long-term health of the program. Typically, you will only consider your immediate need. Thus, what seems to you like an obvious quick win by just making a small change might be a change that breaks vmdb2 for others, or it might be likely to cause headaches for me later on. * Don't assume I know what you're talking about. Assume I'm an unusually ignorant person. Spell things out for me. If, for example, you need vmdb2 to gain support for a new boot loader, tell me how it's going to be installed. Ideally, show me a short, simple, straightforward shell script that installs the boot loader onto an empty disk image, preferably without involving vmdb2 at all. * Don't assume I will do research to implement the change you need. I don't enjoy trying to decipher technical documentation for hardware I don't have. Things are more likely to happen if you spoon feed me what I need to know. Also don't assume I have the hardware to test changes. Be prepared to answer my many ignorant questions, and to test any changes I may make. If I don't get answers or feedback that my changes work, I'm likely to just drop the change and go do something else that's more fun. * I'm happy to get patches to add features or bug fixes. However, I want them to be consistent with the rest of the code base and test suite. Thus I may ask you to make changes before I merge. * I do want to work with you so that vmdb2 is useful for you. I'm just old and tired and slow, and I need you to help me help you.