Purpose of the Asterisk bug tracker

The Asterisk Bug Tracker is used to track bugs and miscellaneous (documentation) elements that need to be discussed in a permanent, semi-threaded manner and which can more easily store programmatical or textual difference files ("diff -u") in a manageable way. The bugtracker is designed to allow the user community to work on different issues so that the brunt of the work is moved from the shoulders of the small development staff onto the more distributed group.

The primary use of the bugtracker system is to track bugs, where "bug" means anything that causes unexpected or detrimental results in the Asterisk system. The secondary purpose it is to track some of the miscellaneous issues surrounding Asterisk, such as documentation and commentary.

Note: Features requests are no longer submitted to or accepted through the bug tracker. Features requests are openly discussed on the mailing lists and Asterisk IRC channels and made note of by Bug Marshalls.

How to report bugs

The following information is necessary to obtain prior to you submitting a bug properly and in a manner that will get it repaired in the shortest possible time:

1. SVN revision number ("svn info")
   If this is not the most updated SVN, please make sure you update to get the latest then check the code. The bug may have already been fixed.
2. Platform (O/S)
   Provide the distribution of software you are currently running. Provide the distribution version ("Linux Redhat 9.0" as an example.)
3. Is the problem reliably repeatable?
   If not, you'll need to be EXTREMELY detailed in giving your configuration notes and including as much debug information as you possibly can, as non-repeatable problems tend to be almost impossible to guess resolution types.
4. Debugging output
   (See the notes below on "SIP", "valgrind" and "gdb") Include all your outputs from various traces, debugging, etc, as attachments and NOT as pasted text in the bug report. The bugtracker does funky things with line wrapping, etc. and an attached file makes more sense.
5. Search the bug tracker. Make certain the bug doesn't already exist.
   Please be diligent in reading all of the possibly relevant bugs. This may take some time, but duplication is a real pain. Plus, in reading the other bugs you might find something useful.

Now that you've done all that, make sure to include all relevant configuration files. Don't just give short snippets; very often there are extremely important things in the config files that you think aren't important, but hold the key to the problem.

If people who are testing the bug cannot replicate it on their own machines, you may be requested to have someone log into your system to take a look around. Of course, it is your discretion that allows this type of access, but it will speed up the process greatly.

Adding new features to Asterisk

We all love new features, but new features bring new complexities, and new complexities bring new bugs. So, to help cut down on new bugs being introduced with your new features, please consider as much of what you're touching as possible. In other words: everything is linked in very subtle ways; make sure you look very closely at each piece of what your patch influences before you submit it. Don't be afraid to submit revised copies of the patch if that's what's required. Bug marshals are there to help you and their suggestions are based on their experience of working with Asterisk.

Make sure you read the Coding Guidelines and make your code compliant with these. Add comments that explain your code in Doxygen format to make it easier to understand both for the committers and for other developers and users.

I'm not a programmer, but this feature would be great...

Not a programmer? Have a feature idea? That's fine, but don't expect to see it anytime soon unless you put a bounty on it (see "bounty" below.) If you do decide to put in a request for a feature, please make sure you think about it completely. Where you can, put examples of what the relevant config file changes might look like, or the error messages the change might print out. Please include specific reasons as to why the change is required, not just by you, but by others who might encounter the same situation. Please do NOT submit general, vaporous feature requests like "I think Asterisk should have a better interface!" Non-specific requests will be unceremoniously deleted by the admins, and you will receive negative kharma points.

In summary: think about your feature. Think about it some more. Ask some people on the IRC channel about it. Wait a few hours, re-read your offline text, and think some more. Wait. Think about it one more time. Then post the feature request to the bug tracker.

Feature requests are generally kept open a week for discussion, then closed and stored in the bug tracker archive.

Testing a patch

After you create a new feature or bug patch submission, it will need to be tested before it can be committed to the SVN repository. By "tested", we mean that multiple persons other than yourself should patch/run/abuse the patch in various manners so that all possible variations of input/output are run through the test. In instances where there are limited test environments, please document exactly how and why you were unable to get others to test the patch so that the developers know that this simply isn't "waiting for testing" and is in fact ready to go. Insufficient testing is a sure way to have your feature put on the back burner - the SVN maintainers don't have time to run exhaustive tests on each new feature. Find people on the #asterisk IRC channel who may be useful/clueful enough to test things for you, and develop a working relationship with other Asterisk users so that you can swap testing routines; this greatly speeds the process. Mail the mailing lists, informing other Asterisk users about your patch and ask for feedback.

So, my feature [was good, was tested, cured cancer] but it still didn't make it into SVN! What can I do?

Many times, a feature that might sound good to you and might work as expected just isn't important enough to make it into the system if it isn't deemed useful to a large enough audience. This is, of course, a subjective decision by the SVN maintainers and the bug marshals. Their opinions can be swayed if enough users get together and rally around a particular feature that seems to be useful to them, so getting others to chime in on your neat request will perhaps advance it further towards the top of the queue, or get it included where previously it was not seen as useful to anyone other than yourself. Sometimes, it's just a matter of timing - nobody has had the time to look at it yet. It's perfectly legitimate (and good) for someone who has a bug or feature request to go to IRC and lobby for it with the bug marshal to try to push it through, schedule time, etc.

Opening an issue in the bug tracker - a checklist

The following applies both if you are opening a bug report or contributing a new feature to Asterisk, Zaptel or libpri:

1. Naming your report
   It is important that you name your report appropriately. Giving it a topic of "Asterisk crashes my server" or "My mother in law annoys me" doesn't help. A detailed and good short description will help the bug marshals and developers to browse through the bug tracker and find your issue quickly. It is common use on the Asterisk bug tracker to put the text (minus quotes, but including brackets) of "[patch]" as the first part of a bug short description when the particular bug includes a sourcecode patch. This helps the developers sort things appropriately (we'll let you guess which bugs get worked on first.)
2. Categorizing your issue
   Make sure you open your report in the proper category. Developers tend to watch "their" area and if you report an H.323 problem in the Applications category it may not get the attention you want.
3. Format of patch
   Please use "diff -u" or "svn diff" on all your patches. Patches which include alternate formatting are almost certainly going to be thrown out or ignored; there are too few hours in the day to wade through difficult-to-follow C code fixes without the help of "diff -u".
4. Use latest code
   Please use the newest version of SVN code (svn trunk) for the appropriate branch of the tree when you submit changes. Very often, problems are fixed in the latest version of the code, and you might be fixing something that is already a known and repaired issue, so a rule of thumb is to either use SVN code that is less than 24 hours old when you submit patches
5. Be careful with your %&!!#* language
   Use complete sentences, capitalization, and avoid slang. This especially applies to non-native English speakers who may have picked up bad habits from IRC channels. Bad English is not a problem, but bad English learned from IRC is worse (i.e.: "d00d, zaptel is fux0red!") The ability of others to understand your comments directly corresponds to rapidity of reply. Asterisk is an international community and we have to try to avoid misunderstandings caused by accidental use of bad language.
6. SIP problem?
   Include debug output! Please include output from "sip debug" if you have a SIP problem. This seems obvious, but apparently is not. Set debug to 4, verbose to 4, turn on sip history and dumphistory in sip.conf and capture all output. A packet trace from ethereal will not tell us what is happening inside your Asterisk server, so that is not a replacement.
7. Maintaining files
   Please ask bug marshals to delete older versions of your patches or files on a ticket if you have updated them to newer versions. Too many versions gets very confusing. Make it very clear for the readers which files they have to use to create a working solution based on your patches.
8. Attach files
   Patches and debug messages should be attached as files, not pasted into the comments area. Plain text files are preferred so they can be read within the web browser environment.

What can I do to help?

There are some obvious things you can do to help the process along. If you're not a programmer, you can still help. Pick some bugs that have patches, and patch a copy of Asterisk. (We assume that even if you're not a programmer, you can "patch -p0 < patchfile.blah" and re-compile.) Test the patch. Run it on your hardware, and comment on the ability of your system to work or not work with that particular patch or bug. There will probably be bugs in the system which have more discussion than others, and they may effect you - comment on them, if commentary is timely and useful. Just as importantly, if someone reports a bug in some way that they think they can replicate, try to replicate it. If you can, say so. If you can't, say so. There are a huge number of tickets that get opened on phantom bugs, because someone's configuration is broken, or they have bad hardware, or what-have-you; the project needs more people simply verifying what someone has said to be a problem, or disproving it as not being a problem in all instances.

If you are a programmer, your patches are desired. Make sure that there is not already a patch waiting in the system that does the same thing, as is often the case. Then, submit the patches and start a test cycle with some other users, as described above.

If you really want to help out and show a lot of promise in the field of arranging bugs and commenting on them, it is possible for you to get write permission into the bugtracker. This will allow you to close/comment/alter bugnotes. Talk to one of the current bug marshals (as they're called) or one of the Digium folks about this if you have such a desire. This implies that you have about 6-10 hours a week to herd the bugs and then work with various developers in getting the bugs resolved or closed out.

Hey! My bug/patch was closed out and it's not fixed!

The bug marshals will try to get more data on a bug if there insufficient commentary or debug information given in the ticket. If there are questions posted as follow-ups to your bug or patch, please try to answer them - the system automatically sends email to you every time a bug on which you've commented has been updated. If the original poster of the patch/bug does not reply within some period of time (usually something like a few weeks) and there are outstanding questions, the bug/patch may get closed out, which would be unfortunate.

If your bug is determined to be a configuration error or something that is clearly not reproducible, it may be closed immediately by a bug marshal. If you believe this to be in error, please go in and edit the bug and say so, or comment to the bug marshal that made the closure (visible on the ticket itself.) If that fails, bring it up on the mailing list(s) and it will be sorted out by the community.

So what's this about a bounty on bug fixes?

It is the case that some corporate users of Asterisk will pay you hard cash for your work on developing patches and bug fixes. Often, there are reasons that a firm can't or won't fix/patch Asterisk internally, and wants to outsource that work to the larger Asterisk community. These patches follow the same licensing rules as everything else for Asterisk that is submitted to the bugtracker: if the author has signed a contributor license agreement, and the patch is in the bugtracker, it's considered fair game to be included in the version of Asterisk that Digium maintains.

The Asterisk community wins whenever a bounty bug is resolved because everyone benefits from that work. The company sponsoring the bounty wins, because their specific problem is fixed. And, of course, the programmer wins because they're paid. Bounty arrangements are between the sponsor and the programmer, and are NOT via Digium or any other third-party middleman. Payment terms, guarantees, etc. etc. are the problem of the two parties (programmer and bounty sponsor) and the bugtracker simply permits an open forum for discussion of the problems and for the bounty. If there are multiple resolutions to a bounty, it is the sponsor's sole discretion to award the payment or not. As noted above, any feature request or bug report that has a bounty bounty on it should have (minus quotes, including brackets) the term "[bounty]" at the front of the short description line. All bug reports that are bounty oriented will be public and GPL, and we will actively discourage/delete non-GPL arrangements that are based on bug reports in the open-community bugtracker (i.e.: you will incur the wrath of the bug marshal posse.)

The contributor license agreement

All patches and features (and commentary, for that matter) are assumed to be "public use" once on the bug tracker. If you have not signed a waiver, your code will NOT GET INTO ASTERISK. Please read and electronically sign the Open Source Contributor License upon logging in to bugs.digium.com.

The reason for the contributor license agreement has been discussed many times, but the general gist is that your contribution must not introduce any encumbrance to the Asterisk code base, but Digium DOES NOT OWN your contribution, and they cannot take released Asterisk out of GPL. Relax; it's a very fair and reasonable disclaimer, and does not remove your rights or threaten the open source nature of the project. See the mailing list archives for long explanations of why everyone who contributes agrees that it's a fair and sane thing to do. You only need to sign the contributor license agreement once; it applies to all stuff that you send in via the bugtracker.

The issue tracker keeps a record of contributions and the license agreements that were in effect when those contributions were uploaded; it also restricts access to uploaded patches when a valid license agreement was not in effect at the time the upload occurred.

What this means to you is the following:

• If you do not have a valid license agreement on file, you will not be able to upload a contribution that contains code; the system will remind of you this fact and give you a link to sign a license agreement.
• If you sign a license agreement and then upload a patch, your patch will be in the system but restricted from access by anyone (except you) until your license agreement is accepted. During this time your patch will show '[License PENDING]'.
• If your license agreement is rejected for any reason, the status of your patch will change to '[License REJECTED]'. If this occurs, your patch will need to be re-uploaded, because even if you sign a new license agreement and it is accepted, it will not apply to patches you uploaded before you signed it.
• If you upload a patch and do not mark it as a code submission, and a bug marshal or developer later determines it to be a code submission, they will most likely delete your patch and ask you to re-upload it, properly marking it as a code submission. If you do not have a license agreement on file, and they choose to mark the patch as a code submission for you, the status of the patch will change to '[License NONE]' and the patch will still not be accessible to anyone and will require re-uploading.

Summary

What will slow down my bug/patch from being looked at:

• No patch code (for features or some bugs)
• Poor descriptions
• No backtrace or debug information (in crash instances)
• No followup to questions by others
• Not having a contributor license agreement on file with Digium

What will speed up my bug/patch being implemented?

• Testing by 1 or more others to reproduce events or use patch
• Good discussion by others in the bug notes
• Clear C code with excellent comments
• Clear debugging packet traces (for protocol-level VoIP issues)

What does the Asterisk community need?

• More testing by everyone to keep developer head-scratching time to a minimum. Testing award you karma points in the issue tracker.