Asking Developer Questions

This page applies to all subprojects and teams listed here. Note that the document was originally written for the hypervisor project which uses the xen-devel and xen-users lists. For other projects, such as the Windows PV Driver project just replace xen-devel with win-pv-devel. For an exact breakdown of the lists, check the list information on the team page or check the list directory!

How to get your question answered on xen-devel

This document is about asking technical questions on the developer list. For advice on posting to the users' list, see XenUsersQuestions and XenUsersNetiquette. For advice on how to report problems, see Reporting Bugs against Xen.

Most of the Xen Project developers actually enjoy answering well-considered, well-expressed questions. But a question, even an interesting one, that's not either of those things is a lot less fun. For example, an email like this:

  From: AwesomeSauXe <hyns783nf@xxxx>
  To: xen-devel@lists.xenproject.org
  Subject: Help

  How function sh_unpin works???

  Thanks.

is going to take at least a few rounds of email before it's clear what's going on. When someone answers this, it will be because they feel they ought to; and by the time they've got all the extra information they need to give a useful answer, they'll be a bit annoyed with the whole business. And that's not going to lead to the most helpful possible answer.

But if the question is clear and sensible and interesting, and if the person asking is (or looks like they will be) a useful contributor to the Xen Project community, then other developers will be happy to answer it, suggest approaches, and sometimes even write patches.

So how do you make _your_ question one that people _want_ to answer?

Think about exactly what your question is.

First, try to get a precise idea of what you want to know. If you don't know what the question is, there's no chance that the person trying to answer it will know. If you ask a vague question, you'll get (at best) a vague answer and need to follow up with the thing you actually wanted to know. I often find that the discipline of deciding exactly what the question is makes me realise what the answer is without even having to ask.

Now that you know what your question is please consider whether xen-devel is really the correct forum for it. Perhaps your question would be better suited for the xen-users list? In particular if your question is regarding the installation or configuration of a Xen system then xen-users should be the preferred list in the first instance.

Use your tools.

Some questions can be answered without specialist knowledge. Always try a search engine first; that might pick the answer out of a wiki or the list archive. Use developer tools like ctags or cscope or an IDE (or grep) to find your way around the code. If you're working directly with hardware registers or comms protocols, get a copy of the reference docs and read it. Asking a question on xen-devel that could be answered easily with a search tool may get you an answer, but it also makes you look like a Bad Engineer, which makes it less likely that someone will read and answer your next question.

Conversely, even if your search doesn't answer the question, it will help you understand the question better.

Set the scene.

If this is your first time on xen-devel, introduce yourself. It's usual to give your name and affiliation, but not essential. Don't tell your life story, but say hi, and say how you work with Xen. Are you a sysadmin, or a kernel hacker, or a researcher (or all of the above)? That lets people know what kind of answer is appropriate. Also it makes them see you as a person, not some random string of characters @gmail.

Next, what's your overall aim? If you're debugging a hosting facility, say so. If you're working on some cool new feature, _definitely_ say so: that makes it clear that helping you brings a direct benefit to the Xen Project. Also, it may be that there's some much better way of doing what you want that avoids the whole problem; and that's much more useful than an answer to the immediate question.

Express your question as clearly as you can.

Having given enough background to explain why you're asking this question, ask the question. Do it as plainly and clearly as you can. Give enough detail that someone who's not familiar with your work can figure out what you're doing (but don't just post your entire code and say "where is the bug?").

As it happens, xen-devel discussions happen in English, so if you don't speak English well, consider getting someone to help you. Also, remember that the person reading your question can't see into your head: you need to try and formulate the question in terms that _they_ will understand. Try not to use the jargon of your own project or OS.

Try to be civil too. You may well be furious and frustrated after a week fighting some horrible piece of Xen Project code, but remember your aim is to get the authors of that code to help you, so calling them names isn't a good idea. Find another outlet for your rage, and ask nicely.

Observe list etiquette.

xen-devel, like many open-source mailing lists, keeps to a set of conventions established in the '80s and '90s. They may seem a bit archaic these days, but breaking them is another way to make yourself look like a Bad Engineer. There are a number of guides on the web, but some particular points that seem to show up on xen-devel are:

• Please post in plain text (i.e. not HTML), word-wrapped to somewehere around 72 characters.
• Please don't top-post. Meaning answer below the asked question, not on the first line of the email.
• Please trim the quoted material in your reply to only include the bits you are responding to.
  • This is particularly important if reply to the digest mail. Be sure to trim down to at most the mail you are responding to as well as adjusting the Subject line to reflect that mail rather than the digest title.
• Please start a new thread for a new question (don't just reply to a random email from the list).
• Please don't email questions directly to xen developers. Keep the conversation on the list where other people (and search engines) can see it. This also applies to private instant messaging.
• Please do not cross post to multiple xen-* mailing lists. Please pick the one which most suits your questions. An exception can be made when moving a thread between lists (e.g. from xen-users to xen-devel).