The mailing list is the primary source for help on FreeSWITCH related questions/problems. However many users are unable to get full mileage from the list as they are inexperienced in formulating their questions and in interacting with the list members. This page seeks to address this problem. Many members of the list, including core developers, take a lot of time and trouble to patiently answer questions asked, and we users should take as much trouble to ask properly formulated questions. Try to follow the steps outlined below to make for a more pleasant and rewarding experience on the list.
Reporting a bug?
Read this first! http://wiki.freeswitch.org/wiki/Reporting_Bugs
Do your homework!
- Most of the time, Google holds the answer to your question.
- Don't expect a 'one-shot / copy-and-paste' answer, there may be some work involved.
- Don't give up on the first page, it's not unusual to go as far as 400-600 results (depending on how relevant each hit is)
- Don't be afraid to dive deep into the FreeSWITCH source code (this is a great way to learn + find hints about what caused your problem)
- Look through the freeswitch-users mailing list archive
How to use Google
Lets say you are looking for information relating to "sofia.conf", just typing that into Google alone usually won't help, you need to give it some context. Here are some examples;
"sofia.conf" freeswitch "sofia.conf.xml" freeswitch "mod_sofia" freeswitch (config|configuration) "sofia.c" freeswitch drops freeswitch "call (drops|dropped)" freeswitch "mod_xml_curl" debug "fscli" freeswitch "MySQL" freeswitch (CDR|cdrs)
Tips and Tricks
Showing as much debug as possible;
console loglevel debug
Getting a SIP trace;
sofia global siptrace on sofia global siptrace off
Preparing your question
- Put a meaningful subject line - 'newbie needs help' *may* bring you a donation, but is otherwise useless. Use the keywords you used in your search.
- Indicate what your end goal is (or is not)
- Include stacktrace where applicable. Make sure you *paste* the *full* stacktrace. Do not worry about using up space - you are not paying for it.
- Include a tested example of the code/config you are using.
- Indicate what attempts you have made to resolve the problem/issue yourself
- Ask yourself, what extra information might you need to resolve similar problems?
- Finally: proofread your question multiple times, rewriting for clarity and brevity as needed. You will greatly increase the chances of both getting help and figuring out your stumbling block this way.
- Post a user question to the developers' mailing list or IRC channel.
- Start a new discussion on an existing thread. Start a new thread for a new topic.
- Expect an instant or one-shot answer. The mailing list is not your personal tutor.
- Be vague e.g. "please help me build a phone system". No one has time to write a vague answer.
- Keep repeating the same question. If anyone has an answer, you will get it sooner or later. If you post on a Friday or a weekend wait till people have a chance to * get over their Monday hangover before expecting a reply.
- Obfuscate your code or invent code/config snippets - if you are reading this, your code/config is not rocket science and no one is going to steal it. Probably no one will take it even if you pay them.
- Use the phrase 'it doesn't work'. The most common question on IRC is: 'What does doesn't work mean?'
- Attempt to 'bump' your question by reposting it a second time. The mailing list is not a phpBB bulletin board.
For many of us, English is not our native language. Try to follow English syntax, but do not waste everyone's time by apologizing. People will realise your difficulty and will ask for clarification if needed. However, please avoid using 'sms-speak' and refrain from being overly casual.
i wan 2 make cms pls cn u hlp asap
Formatting your emails/replies
Try and use in-line comments where possible, this will help people determine what part of your reply relates to your previous email.
I have checked this config and it is working fine. Can you tell me what is causing the problem? >> (some code here) > You are having problems because of a sofia.conf typo >> (some code here) > You are also having problems because of compile time errors
>> (some code here) > You are having problems because of a sofia.conf typo I have checked this config and it is working fine, here is proof; (some code here) > You are also having problems because of compile config typo >> (some code here) Can you point out which part of the config has the typo?
- Always make an effort to say thank you.
- If you feel someone did not understand your request (or gives an unrelated answer), then it's important you express this to them, and clarify further.
- Always make an effort to make your findings public. This may be in the form of a Django core ticket, djangosnippets.org, blog post, YouTube video etc. (Although sometimes, if the mailing list subject is descriptive enough, it may suffice to just have it in archive - which happens automatically.)
Like any project, if you show willingness to help and contribute then others are more likely to help you in the future.
Although it is not officially advertised, most of the core developers will participate in the 5-for-1 scheme. In a nutshell, if you spend time doing triage on 5 other tickets, you can request a core developer to look at any ticket of your choice.
The following guidelines apply;
- For every 1 hour you put in, you will get back roughly 3-5 minutes.
- The core developer won't necessarily offer a fix, but will give the ticket their full attention and generally give a more detailed response
- Typically speaking, a minimum of 30 minutes is a good guideline on how much time to spend in triage.
- If you spend 30+ minutes in triage on a single ticket, you can do a 1-for-1 request, but make sure you explain this in your mailing list request (as shown below)
Send your request to the list in a clear and concise manner, outlining what triage you did, what action was taken on each, and what ticket you would like in return, for example;
Subject: 5-for-1 request I have spent approx 1 hour doing triage on the following tickets; * http://jira.freeswitch.org/browse/FS-xxxx - requested further info * http://jira.freeswitch.org/browse/FS-xxxx - added comments, needs review from core dev * etc etc In return, could a core developer please look at the following ticket; http://jira.freeswitch.org/browse/FS-xxxx
Remember the FreeSWITCH community are all volunteers, and demanding a reply is never going to end well.
If you have an urgent situation, you can consider one of the following;
- If you have a ticket with a feature request, throw up a bounty on the ticket and post into the mailing list
- If you need a review from a core developer, try send 50 bucks to email@example.com, and that will probably get you a few minutes of Tony's time (BDFL of FreeSWITCH) to comment on your ticket. Although it would be more useful if you participated in the 5-for-1 instead.