Difference between revisions of "Asking Developer Questions"

From Xen
(Migrated from http://wiki.xen.org/xenwiki/AskingXenDevelQuestions)
 
(Observe list etiquette.)
 
(17 intermediate revisions by 4 users not shown)
Line 1: Line 1:
  +
{{InfoLeft|This page applies to [http://www.xenproject.org/help/mailing-list.html#devel developer mailing lists] of '''all subprojects and teams''' listed [http://xenproject.org/developers/teams.html here]. If you don't know the developer list, you can find the list information on the [http://xenproject.org/developers/teams.html team page] or in the [http://www.xenproject.org/help/mailing-list.html#devel list directory]!}}
<!-- MoinMoin name: AskingXenDevelQuestions -->
 
<!-- Comment: Trim your quotes please! -->
 
<!-- WikiMedia name: AskingXenDevelQuestions -->
 
<!-- Page revision: 00000004 -->
 
<!-- Original date: Tue Jul 19 11:16:50 2011 (1311074210000000) -->
 
 
 
__NOTOC__
 
__NOTOC__
= How to get your question answered on xen-devel =
+
= How to get your question answered on xen-devel, mirageos-devel, win-pv-devel, etc. =
   
''This document is about asking technical questions on the developer list.
+
''This document is about asking technical questions on the developer lists.
For advice on posting to the users' list, see [[XenUsersQuestions]] and [[XenUsersNetiquette]].
+
For advice on posting to the users' list, see [[XenUsersQuestions|User Questions]] and [[XenUsersNetiquette|List Netiquette]].
For advice on how to report problems, see [[ReportingBugs]].''
+
For advice on how to report problems, see [[Reporting Bugs against Xen|Reporting Bugs]].''
   
Most of the Xen developers actually enjoy answering well-considered,
+
Most Xen Project developers actually enjoy answering well-considered,
 
well-expressed questions. But a question, even an interesting one,
 
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
 
that's not either of those things is a lot less fun. For example, an
 
email like this:
 
email like this:
   
  +
<pre>
 
  +
From: AwesomeSauXe <hyns783nf@xxxx>
<pre><nowiki>
 
  +
To: xen-devel@lists.xenproject.org
From: AwesomeSauXe <hyns783nf@gmail.com>
 
To: xen-devel@lists.xensource.com
 
 
Subject: Help
 
Subject: Help
   
Line 26: Line 20:
   
 
Thanks.
 
Thanks.
</nowiki></pre>
+
</pre>
   
 
is going to take at least a few rounds of email before it's clear what's
 
is going to take at least a few rounds of email before it's clear what's
Line 37: Line 31:
 
But if the question is clear and sensible and interesting, and if the
 
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
 
person asking is (or looks like they will be) a useful contributor to
the Xen community, then other developers will be happy to answer it,
+
the Xen Project community, then other developers will be happy to answer it,
 
suggest approaches, and sometimes even write patches.
 
suggest approaches, and sometimes even write patches.
   
Line 52: Line 46:
 
ask.
 
ask.
   
Now that you know what your question is please consider whether xen-devel
+
Now that you know what your question is please consider whether a
  +
[http://www.xenproject.org/help/mailing-list.html#devel developer list]
 
is really the correct forum for it. Perhaps your question would be better
 
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
+
suited for the xen-users or another [http://www.xenproject.org/help/mailing-list.html#general user list]?
  +
In particular if your question is regarding
 
the installation or configuration of a Xen system then xen-users should be
 
the installation or configuration of a Xen system then xen-users should be
 
the preferred list in the first instance.
 
the preferred list in the first instance.
Line 62: Line 58:
 
Some questions can be answered without specialist knowledge. Always try
 
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
 
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
+
list archive. You can also use [http://xen.markmail.org/ xen markmail].
  +
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
 
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
 
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
+
and read it. Asking a question on [http://www.xenproject.org/help/mailing-list.html#devel developer list] that could be answered
 
easily with a search tool may get you an answer, but it also makes you
 
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
 
look like a Bad Engineer, which makes it less likely that someone will
Line 73: Line 70:
 
help you understand the question better.
 
help you understand the question better.
   
  +
== Pick the right list. ==
  +
  +
If you do not know which developer list is for you, either check the
  +
[http://www.xenproject.org/help/mailing-list.html#devel developer list directory] or
  +
the [http://xenproject.org/developers/teams.html team pages].
  +
 
== Set the scene. ==
 
== Set the scene. ==
   
If this is your first time on xen-devel, introduce yourself. It's usual
+
If this is your first time on a Xen Project [http://www.xenproject.org/help/mailing-list.html#devel developer list], introduce yourself. It's usual
 
to give your name and affiliation, but not essential. Don't tell your
 
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
 
life story, but say hi, and say how you work with Xen. Are you a
Line 85: Line 88:
 
say so. If you're working on some cool new feature, _definitely_ say so:
 
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
 
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
+
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
 
what you want that avoids the whole problem; and that's much more useful
 
than an answer to the immediate question.
 
than an answer to the immediate question.
Line 97: Line 100:
 
say "where is the bug?").
 
say "where is the bug?").
   
As it happens, xen-devel discussions happen in English, so if you don't
+
As it happens, [http://www.xenproject.org/help/mailing-list.html#devel developer list] discussions happen in English, so if you don't
 
speak English well, consider getting someone to help you. Also,
 
speak English well, consider getting someone to help you. Also,
 
remember that the person reading your question can't see into your head:
 
remember that the person reading your question can't see into your head:
Line 104: Line 107:
   
 
Try to be civil too. You may well be furious and frustrated after a
 
Try to be civil too. You may well be furious and frustrated after a
week fighting some horrible piece of Xen code, but remember your aim is
+
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
 
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.
 
a good idea. Find another outlet for your rage, and ask nicely.
   
  +
{{Anchor|etiquette}}
 
== Observe list etiquette. ==
 
== Observe list etiquette. ==
   
  +
Xen Project [http://www.xenproject.org/help/mailing-list.html#devel developer lists],
xen-devel, like many open-source mailing lists, keeps to a set of
 
  +
like many open-source mailing lists, keeps to a set of
 
conventions established in the '80s and '90s. They may seem a bit
 
conventions established in the '80s and '90s. They may seem a bit
 
archaic these days, but breaking them is another way to make yourself
 
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,
 
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:
+
but some particular points that seem to show up on our [http://www.xenproject.org/help/mailing-list.html#devel developer lists] are:
   
 
* Please post in plain text (i.e. not HTML), word-wrapped to somewehere around 72 characters.
 
* 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 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.
 
* 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 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.
+
* 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).
 
* 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).
   
[[Category:Developer]]
+
[[Category:Developers]]
  +
[[Category:Development Process]]
  +
[[Category:Xen]]

Latest revision as of 12:14, 21 October 2014

Icon Info.png This page applies to developer mailing lists of all subprojects and teams listed here. If you don't know the developer list, you can find the list information on the team page or in the list directory!


How to get your question answered on xen-devel, mirageos-devel, win-pv-devel, etc.

This document is about asking technical questions on the developer lists. For advice on posting to the users' list, see User Questions and List Netiquette. For advice on how to report problems, see Reporting Bugs.

Most 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 a developer list is really the correct forum for it. Perhaps your question would be better suited for the xen-users or another user 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. You can also use xen markmail. 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 developer list 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.

Pick the right list.

If you do not know which developer list is for you, either check the developer list directory or the team pages.

Set the scene.

If this is your first time on a Xen Project developer list, 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, developer list 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 Project developer lists, 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 our developer lists 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).