Ns-3-users-guidelines-for-posting

From Nsnam
Revision as of 18:15, 10 March 2017 by Pdbarnes (Talk | contribs) (Preliminaries: Add exceptions and crashes section)

(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

Preliminaries

This is the short form of our posting guide. More lengthy explanations are in section 2.

Do your homework

Work through the tutorial, all of it

Read the documentation about models and the reference manual

Search the Google Groups to see if your question was asked before

Subjects/topics

Search for related discussions

Add to existing threads if the last reply is less than a year old. If older than a year, start a new thread, specifically linking to the prior thread.

Use a specific subject line

Do not ask unrelated questions in reply to a topic about something else. Start a new thread with a specific subject line.

Information to include in your message

Platform

If you are reporting a problem such as a installation failure, please report enough details about your platform to allow a maintainer to reproduce.

Source Code

Use the attachment feature for posting scripts; only short snippets (less than 10 lines) should be inline.

Create the simplest possible script which illustrates the issue you are facing.

It’s almost always impossible to give a helpful reply when looking at a snippet from a larger script, or worse a snippet which refers to code models not part of the distribution.

If there is the remotest chance you changed something in an ns-3 module, state that up front. Attach your modified files and a minimal main script that triggers the problem.

Exceptions and Crashes

Exceptions and crashes are a normal part of debugging. Learn to use a debugger; this isn't the right place to ask what to do next when the gdb> prompt appears. When someone (or an error message) suggests running your script in a debugger, expect to do some work to learn more about what's going on, beyond just the stack trace. it's almost always impossible to make useful suggestions from just that. Don't waste everyone's time, including yours, by just posting it and asking for help. Reread the previous section on #Source Code.

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

This is the long form of the posting guide, summarized above.

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 5000 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)

Good manners:

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.

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.

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 comfortable with ns-3-users. The ns-developers mailing list is friendly as well, but it assumes that you have some 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.

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.

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 chances 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.
  • Use professional writing guidelines to convey information in a clear, efficient way
    • No profanity, and never do jokes about sex, religion, culture, or about someone's misuse of the English language. You can be funny without being offensive.
    • Avoid interactions that could be considered to be harassing or mocking someone else. If you are interacting with someone who you feel is not making a fair effort to follow the list guidelines, it is best to just stop replying further, rather than to post something out of anger or frustration or to try to get the last word in.
    • Keep in mind also, if writers are trying their best not to be offensive, readers should try not to be offended too easily.
    • Do not plead (e.g., repeatedly asking the same question or with capitalization or many exclamation points) if you do not get the answer you want as quickly as you may want it.
  • 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).

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.

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).