diff options
Diffstat (limited to 'documentation.mdwn')
| -rw-r--r-- | documentation.mdwn | 76 |
1 files changed, 76 insertions, 0 deletions
diff --git a/documentation.mdwn b/documentation.mdwn index 797b910..42581f2 100644 --- a/documentation.mdwn +++ b/documentation.mdwn @@ -4,3 +4,79 @@ The vmdb2 manual is published at: * <https://vmdb2-manual.liw.fi/> (HTML) * <https://vmdb2-manual.liw.fi/vmdb2.pdf> (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. |