diff options
Diffstat (limited to 'documentation.mdwn')
| -rw-r--r-- | documentation.mdwn | 76 |
1 files changed, 1 insertions, 75 deletions
diff --git a/documentation.mdwn b/documentation.mdwn index 42581f2..6e59ed8 100644 --- a/documentation.mdwn +++ b/documentation.mdwn @@ -5,78 +5,4 @@ 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. +See also the page on [[contributing]] to vmdb2 development. |