From b74d4f43ec255e0a525d4b70309e930ce0d2b1d2 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Tue, 13 Apr 2021 08:24:58 +0300 Subject: update docs for contributing to vmdb2 --- contributing.mdwn | 63 ++++++++++++++++++++++++++++++++++++++++++++ documentation.mdwn | 76 +----------------------------------------------------- index.mdwn | 1 + 3 files changed, 65 insertions(+), 75 deletions(-) create mode 100644 contributing.mdwn 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 gitlab.com [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]: https://gitlab.com/larswirzenius/vmdb2/-/issues +[Debian bug tracker]: https://bugs.debian.org/vmdb2 + +# 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 -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. diff --git a/index.mdwn b/index.mdwn index aeb8a8a..62d047e 100644 --- a/index.mdwn +++ b/index.mdwn @@ -4,6 +4,7 @@ [[Contact]] — [[Code|patches]] — [[Release process|release]] — +[[Contributing]] — [[Documentation]] vmdb2 installs a bare bones Debian system to a disk or disk image -- cgit v1.2.1 From 9c3aea4d8b39fda71598d952836ff4bf6095e9ab Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Tue, 13 Apr 2021 08:26:22 +0300 Subject: chore: update styling from ikiwiki-style --- style.css | 18 ++++++++++++++++++ templates/page.tmpl | 9 +++++++++ 2 files changed, 27 insertions(+) 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 @@ + + + + + -- cgit v1.2.1