diff options
authorLars Wirzenius <>2020-08-17 11:58:15 +0300
committerLars Wirzenius <>2020-08-17 11:58:15 +0300
commit54b97b16f71e5f8f01446c7898544244c7a9646f (patch)
parenteddb0c665e93a2309065e8a102faaa247f24a97f (diff)
doc: add some advice for getting vmdb2 to change
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:
* <> (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
+* 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.