Ns-3-users-guidelines-for-posting

From Nsnam
Revision as of 19:49, 8 December 2015 by Tomh (Talk | contribs) (guidelines for posting)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

Posting Guide: How to ask good questions that prompt useful answers

This guide is intended to make more productive use of the ns-3-users group by recommending best practices for posting questions and answers. Please keep in mind that over 4000 people subscribe to this group, so it is common courtesy to follow this guidance.

If one of the project maintainers responds to your question by citing this guide, please re-read the guidance before asking your question again.

This guide is freely adapted from the R Posting Guide (http://www.r-project.org/posting-guide.html)

The list:

ns-3 is open source software, constructed and maintained by volunteers. They have various reasons for contributing software and participating on the group, but often have limited time. Please help them quickly understand the details about your problem, and please avoid asking questions that have already been answered.

Good manners:

Follow etiquette and professionalism guidelines found in RFC1855 and RFC7704. Please read these if you haven't already.

Customs differ. Some people are very direct. Others surround everything they say with hedges and apologies. Be tolerant. Rudeness is never warranted, but sometimes `read the manual' is the appropriate response. Don't waste time discussing such matters on the list. Ad hominem comments are absolutely out of place.

Note: if moderators find posts that lack etiquette or professionalism, we will follow an escalation path that will result in private and/or public warnings, and eventual ban from the group if behavior is not modified.

Questions about networking protocols:

The ns-3-users group primarily intended for questions and discussion about the ns-3 software. However, questions about networking protocols are sometimes posted. If the question is well-asked and of interest to someone on the list, it may elicit an informative up-to-date answer.

Basic networking and classroom homework:

The ns-3 user group is not intended for basic networking or classroom homework. Feel free to ask questions, but don't ask to help solving a class assignment (it's cheating, and your teacher will find it).

Announcements:

Job postings specific to ns-3 (e.g. postdoctoral or professional appointments related to ns-3 specifically) are allowed. General job postings unrelated to ns-3 are inappropriate.

Calls for participation in events related to ns-3 (e.g. Workshop on ns-3, or other simulation/emulation workshops where ns-3 would be considered a mainstream topic) are allowed. General conference/workshop/journal call for papers are inappropriate.

Which group (or mailing list)?:

ns-3-users or ns-developers? There are two widely used mailing lists for questions and discussion about ns-3.

  • ns-3-users is intended for people who want to use ns-3 but who are not necessarily interested in developing new or extending existing modules for public release.
  • ns-developers is intended for questions and discussion about code development in ns-3, new features, etc.

Questions such as "Does ns-3 support <insert-protocol-model> because I'd like to reuse it if so?" should always be asked on ns-3-users. Questions such as "Is anyone developing a model of <insert-protocol-model> for contributing back to ns-3?" are appropriate for ns-developers or ns-3-users.

New users, or users seeking help in performing a particular task are probably more confortable with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have a thorough knowledge of ns-3, and out-of-scope posts will usually be redirected to ns-3-users.

Please do not post the same message to both lists; pick one. ns-3 maintainers read both lists.

Do your homework before posting:

If it is clear that you have done basic background research and searched already for the answer, you are far more likely to get an informative response.

  • Search the ns-3-users group. The web interface has a nice search feature, use it.
  • Search the web. Use your preferred search engine, you may find good tips.
  • Search the ns-3 wiki, manual and Doxygen.
  • For any result found, pay attention to the post date. Some posts are about very old ns-3 versions, and the solution may not be working anymore. Or the problem may have been fixed altogether.
  • When possible, always use the latest ns-3 release. If you are using an older release, please try to reproduce your problem on the most recent release or development code to see if it has already been fixed.
  • If you have doubts that something changed from release to release, consult the ns-3 changes file (it is named CHANGES.html).
  • If you search for help for an unsupported module (e.g., one not distributed with ns-3-allinone), contact the module developer first.

Useful posting tips:

In order to have more chanches to have a fast and meaningful answer, please do the following:

  • Use an informative subject line (not something like `question', or 'help me').
  • Do not ask another unrelated question by replying to an existing thread with a different subject line; start a new thread instead.
  • Don't expect a reply in hours. Feel free to bump the question, but only after a couple of days.
  • Only reply to recent threads (less then 1 year old).
  • The more threads you ask the same question in, the less you will receive an answer.
  • Do not include more than 10 lines of code in the message. The group allows attachments, use them.
  • The ns-3-users group is not the best place to ask basic C++ questions.
  • If relevant, state clearly the ns-3 version, compiler version, OS (type and version). If you're in doubt if it's relevant, then it is.
    • the ns-3 version can be found in RELEASE_NOTES, the compiler version from g++ --version and the OS type/version from uname -a
  • Some consider it good manners to include a concise signature specifying your affiliation, but this is not required.

Surprising behavior and bugs:

What you think is a bug may be many other things, such as a default behavior that you do not like, a feature, an undocumented feature, or a bug in the documentation. If you think you have found a bug, feel free to discuss about it in the ns-3-users group. In order to simplify the bug processing, please try to do the following:

  • Search the ns-3 Bugzilla for similar bugs. In case, feel free to ask for the estimated resolution time.
  • Debug your script. Using gdb or any debugger GUI is mandatory to discriminate between a ns-3 bug and a mistake in the user's script.
  • Simplify the offending script to the bare minimum. Try to reproduce reliably the misbehaviour in the very latest ns-3 version, possibly ns-3-dev.
  • When opening or replying to a bug, remember that:
    1. Any bug is maximum priority for who found it, but it may not be for others. Be realistic.
    2. Clearly state what was the expected behaviour and the one you got.
    3. Include a script showing the bug.
    4. Bugs are fixed in ns-3-dev. Make sure that your bug is present in ns-3-dev.
    5. If possible, include a patch...

Responding to other posts:

  • Rudeness and ad hominem comments are not acceptable. Brevity is OK.
  • Take care when you quote other people's comments to respect their rights. In particular:
    • Private (non-group or non-list) messages should never be quoted or forwarded to a list without the author's permission. Don't assume "it is OK"-- always ask first.
    • The original authorship and meaning should always be clear.
  • It is common practice to quote prior messages in entirety.
  • If you edit the quoted text from prior messages, include sufficient context so that the content is clear even if your archived message is referenced at a much later date and in isolation from other messages.
  • When responding to a very simple question, use the following algorithm:
    • Check if someone else posted a reply. If the question has just arrived in your inbox, wait half an hour.
    • If no one has posted a reply, then post your reply.
  • Always consider language and cultural barriers. What is friendly in your country may be offensive for others, or simply confusing. Moreover,
    • Never, ever do jokes about sex, religion, culture.
  • Never post something if you are angry. Wait some hours and re-read your message if you composed it while you was upset.

Common posting mistakes:

  • Missing or non-specific message subject
  • Not doing basic homework before posting a question
  • Not being more specific than `function xxx doesn't work'
  • Being overly specific and not stating your real goal; there may be another solution if your underlying goal is better understood
  • Not including version and OS information in question regarding unexpected behavior.
  • Finding a bug in an old version of ns-3 that has been fixed in the most recent version.
  • Claiming that something is a bug when in fact the software is working as intended and documented, just not in the way you first expected.
  • Threatening not to use the software if you cannot get your question answered. Even when intended as a statement of fact, this tends to create negative attitudes.
  • Posting the same question more than once per day (in different threads).

Final words:

It is a skill to ask good questions. If at first you don't get the answers that are useful to you, don't get discouraged. A response that is concise and technically accurate may be just that, and not an intended putdown. If you feel insulted by some response to a post of yours, don't make any hasty response in return - you're more likely than not to regret it. Read Eric Raymond's essay How To Ask Questions The Smart Way for more suggestions, and for insight into people's behavior on technical mailing lists.

Posters should be aware that the ns-3 lists are public discussion lists and anything you post will be archived and accessible via several websites for many years, and we cannot remove any posts (it is a Google service).