diff options
5 files changed, 92 insertions, 75 deletions
diff --git a/contributing.mdwn b/contributing.mdwn
new file mode 100644
index 0000000..c9f61b4
--- /dev/null
+++ b/contributing.mdwn
@@ -0,0 +1,63 @@
+[[!meta title="Contributing to vmdb2"]]
+Please help make vmdb2 better. There are many ways to contribute that
+don't involve writing code.
+* improve the documentation
+ - fix typos or grammar
+ - clarify some part
+ - provide a helpful diagram
+ - write missing parts of the documentation
+* improve the website
+ - fix typos or grammar
+ - fix a layout problem
+ - suggest a helpful link
+ - make a stylish logo?
+* try out the software and report your back your experiences
+ - what went well? what could be improved?
+* help others who have trouble with the software
+ - on IRC, Matrix, or on the issue tracker
+* help the developers understand what you need
+ - document your use case
+* fix a bug
+* add a missing feature
+We co-ordinate our work via the [issue tracker][]; also,
+the [Debian bug tracker][]. Using GitLab requires an account on the
+site: if that's a problem for you, please get in touch and we may be
+able to arrange something.
+[issue tracker]:
+[Debian bug tracker]:
+# Getting vmdb2 to change so you can do what you want to do
+Sometimes it happens you want vmdb2 to do something that it doesn't
+quite know how to do. Here's some advice for that situation.
+* For any substantial discussions, we prefer the issue tracker over
+ chat systems. Chat systems are great for quick questions, but
+ they're also ephemeral and only help the people who happen to be
+ present at the time. The issue tracker lasts longer, and allows
+ long-form replies and taking time to respond in depth.
+* When suggesting or contributing a new feature, please always start
+ by explaining the thing you want to achieve. "I want to create an
+ image that runs on a RISC-V board" is a better start than sending a
+ patch to use a new boot loader. It's easier to judge a change fairly
+ if the need for it is clear.
+* If you contribute a functional change, please also change the
+ automated test suite to verify the changed functionality changes. If
+ you're not sure how to do that, please ask, and we'll help. We rely
+ on our test suite to be able to make large changes rapidly and
+ confidently. (Adding tests for bugs, when they're fixed, would be
+ nice too, but we don't insist on that.)
+Some caveats so you know what to expect:
+* vmdb2 is a hobby project. It might take a while for us to respond.
+ Please be patient. However, if you open an issue, and haven't heard
+ back in a week, ping us on the issue or via a chat system. We try to
+ be prompt, but sometimes work and life get in the way of working on
+ hobby projects.
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:
* <> (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.
+See also the page on [[contributing]] to vmdb2 development.
diff --git a/index.mdwn b/index.mdwn
index aeb8a8a..62d047e 100644
--- a/index.mdwn
+++ b/index.mdwn
@@ -4,6 +4,7 @@
[[Contact]] &mdash;
[[Code|patches]] &mdash;
[[Release process|release]] &mdash;
+[[Contributing]] &mdash;
vmdb2 installs a bare bones Debian system to a disk or disk image
diff --git a/style.css b/style.css
index 88a06e2..9252d88 100644
--- a/style.css
+++ b/style.css
@@ -46,6 +46,7 @@ div.pageheader {
.pageheader span.title {
+ display: block;
font-size: 200%;
font-weight: bold;
font-family: sans-serif;
@@ -130,3 +131,20 @@ div.wisdom p.quote {
.normalPC { font-size: 120%; }
.bigPC { font-size: 150%; }
.biggestPC { font-size: 200%; }
+table {
+ border: 0px;
+ width: 100%;
+th {
+ font-weight: bold;
+tr {
+tr:nth-child(even) {
+ background-color: #f2f2f2;
diff --git a/templates/page.tmpl b/templates/page.tmpl
index 712a65f..849dd7d 100644
--- a/templates/page.tmpl
+++ b/templates/page.tmpl
@@ -19,6 +19,15 @@
<span class="title">
+<nav class="tags">