# Asterisk Project : Asterisk Issue Guidelines

Added by rnewton , edited by rnewton on Aug 01, 2013

## Purpose of the Asterisk issue tracker

The Asterisk Issue Tracker is used to track bugs and miscellaneous (documentation) elements within the Asterisk project. The issue tracker is designed to manage reports on both core and extended components of the Asterisk project.

The primary use of the issue tracker is to track bugs, where "bug" means anything that causes unexpected or detrimental results in the Asterisk system. The secondary purpose is to track some of the miscellaneous issues surrounding Asterisk, such as documentation, commentary and feature requests or improvements with associated patches.

Feature requests without patches are not accepted through the issue tracker and in general are discussed openly on the mailing lists and Asterisk IRC channels. Please read the "How to request a feature" section of this article.

#### What the issue tracker is NOT used for:

- Information Requests (How does X parameter work?) See the forums, mailing lists or IRC channels http://www.asterisk.org/community
- Support requests (My phone doesn't register! My database connectivity doesn't work! How do I get it to work?) Search and ask on the forums, mailing lists and IRC http://www.asterisk.org/community
- Random wishes and feature requests with no patch (I want Asterisk to support <insert obscure protocol or gadget>, but I don't know how to code!) See the "how to request a feature" section
- Business development requests (I will pay you to make Asterisk support fancy unicorn protocol!) Please head to the asterisk-biz mailing list at http://lists.digium.com

#### Why should you read this?

To get the attention of helpful individuals and the Asterisk development team, you'll want to read, understand and act on this article. The steps here will help you provide all the information the Asterisk team needs to solve your issue.

## How to report a bug

#### STOP! BEFORE YOU EVEN THINK ABOUT FILING A BUG REPORT...

Your issue may not be a bug or could have been fixed already. Run through the checklist below to verify you have done your due diligence.

- Verify you are on a supported version of Asterisk: https://wiki.asterisk.org/wiki/display/AST/Asterisk+Versions, i.e. a version of Asterisk that has not reached End of Life
- Are you using the latest version of your Asterisk branch? Please check the release notes for newer versions of Asterisk to see if there is a potential fix for your issue. Even if you can't identify a fix in a newer version, it is preferable that you upgrade when reasonable to do so. Release notes are available in the UPGRADE.txt, CHANGES and ChangeLog files within the root directory of your particular point release. http://svnview.digium.com/svn/asterisk/tags/
- Are you using the latest third party software, firmware, model, etc? If the error scenario involves phones, third party databases or other software, be sure it is all up to date and check their documentation.
- Have you asked for help in the community? (mailing lists, IRC, forums) You can locate all these services here: http://www.asterisk.org/community
- Have you searched the Asterisk documentation in case this behavior is expected? The documentation is located here: https://wiki.asterisk.org/wiki/display/AST/Home
- Have you searched the Asterisk bug tracker to see if an issue is already filed for this potential bug? https://issues.asterisk.org/jira you'll find the search field in the top right of the page.
- Can you reproduce the problem? If you can't find a way to simulate or reproduce the issue, then at least get the system to a point where it's capturing relevant debug during the times the seemingly random failure occurs. Yes that could mean running debug for days or weeks if necessary.

#### What makes a useful bug report?

There are some key qualities to keep in mind. These should be reflected in your bug report and will increase the chance of your bug being fixed!

- Specific: Pertaining to a certain, clearly defined issue with data to provide evidence of said issue
- Reproducible: Not random - you have some idea when this issue occurs and how to make it happen again
- Concise: Brief but comprehensive. Don't provide an essay on what you think is wrong. Provide only the facts and debug output that supports them.

#### Submitting the bug report - information requirements

You'll report the issue through the tracker, under the Asterisk project. https://issues.asterisk.org/jira/browse/ASTERISK

###### 0. Sign up for an asterisk.org account

Account signup for asterisk.org community services (including JIRA, Confluence and FishEye/Crucible) can be found at https://signup.asterisk.org.

###### 1.Create a new issue in the tracker

The "Create Issue" button in the top right hand corner of the page will prompt you for the project and issue type. Pick the Asterisk project, and choose an appropriate issue type.

Issue types:

- Bug
- New feature
- Improvement
- Information request (This type is not currently used, and your issue is likely to be closed or redefined)

###### 2. Fill out the issue form

For a bug you must include the following information:

- Concise and descriptive summary
  Accurate and descriptive, not prescriptive. Provide the facts of what is happening and leave out assumptions as to what the issue might be.
  Good example: "Crash occurs when exactly twelve SIP channels hang up at the same time inside of a queue"
  Bad Examples: "asterisk crashes" , "problem with queue", "asterisk doesn't work", "channel hangups cause crash"
- Operating System detail (Linux distribution, kernel version, architecture etc)
- Asterisk version (exact branch and point release, such as 1.8.12.0)
- Information on any third party software involved in the scenario (database software, libraries, etc)
- Frequency and timing of the issue (does this occur constantly, is there a trigger? Every 5 minutes? seemingly random?)
- Symptoms described in specific detail ("No audio in one direction on only inbound calls", "choppy noise on calls where trans-coding takes place")
- Steps required to reproduce the issue (tell the developer exactly how to reproduce the issue, just imagine you are making steps for a manual)
- Workarounds in detail with specific steps (if you found a workaround for a serious issue, please include it for others who may be affected)
- Debugging output - You'll almost always want to include extensions.conf, and config files for any involved component of Asterisk. Depending on the issue you'll also need SIP traces for anything involving a SIP channel plus backtraces and valgrind output for crashes or memory issues. Unless the issue is extremely trivial, you'll need to also include an Asterisk debug log, including DEBUG and VERBOSE type messages with at least a level of 5. You can find instructions HERE and HERE.

Be courteous. Do not paste debug output in the description or a comment, instead please attach any debugging output as text files and reference them by file name.

###### 3. Submit the issue.

Once you have created the issue, you can now attach debug as files. You are ready to wait for a response from a bug marshal or post additional information as comments. If you are responding to a request for feedback, be sure to use the workflow actions to "send back" the status to the developers.

#### How you can speed up bug resolution

Follow the checklist above and include all information that we require. Watch for emails where we may ask for additional data and help us test any patches or possible fixes for the issue. If you didn't follow the information requirements - it'll often be the first thing we ask for. A developer cannot fix your issue until we have sufficient data to verify the problem.

#### Reasons your report may be closed without resolution

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.

Common reasons your issue may be closed without resolution:

- The issue can't be reproduced from the original report.
- The report lacks sufficient information to investigate, and you haven't responded to our requests for specific information.
- The issue may exist, but can't be fixed due to underlying architecture or infrastructure issues.
- The issue is not a bug, but is a support request. The reporter will be directed to community resources for support.

If insufficient commentary or debug information was given in the ticket then bug marshals will request additional information from the reporter. 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 for every update on a bug you reported. If the original reporter of the patch/bug does not reply within some period of time (usually 14 days) and there are outstanding questions, the bug/patch may get closed out, which would be unfortunate. The developers have a lot on their plate and only so much time to spend managing inactive issues with insufficient information.

If your bug was closed, but you get additional debug or data later on, you can always contact a bug marshal in #asterisk-bugs on irc.freenode.net to have them re-open the issue.

## How to request a feature

Feature requests without patches are not typically monitored or kept on the tracker. Even a feature request with a patch will still have to be approved by the SVN maintainers and community developers. Many people want Asterisk to do many different things; however, unless the feature has some extremely obvious (to many people) benefit, then it's best to have a community discussion and consensus on a feature before it goes into Asterisk. Feature requests are openly discussed on the mailing lists and IRC channels. Most bug marshals and Asterisk developers actively participate and will note the request if it makes sense.

New features and major architecture changes are often discussed at the AstriDevCon event held before Astricon.

If you really need the feature, but are not a programmer, you'll need to find someone else to write the code for you. However just writing a patch doesn't guarantee it'll make it into an Asterisk release. See the paragraphs below on Patch and Code submission.

#### Do you have a feature request and a patch to go with it?

Great, then move on to the Patch and Code submission section below.

## Patch and Code submission

#### Basic patch requirements:

- Make sure you read the coding guidelines and make your code compliant with these.
- Add comments that explain your code in Doxygen format (Qt style) to make it easier to understand both for those that commit and for other developers and users.
- Read the Digium License Agreement section below, and then sign the agreement within JIRA.

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

#### Features and Improvements

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.

Once you have a patch that follows the requirements noted above then you can post it on the issue tracker in the Asterisk project as type "Improvement" or "New Feature".

#### Patch testing & Review board

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 or #asterisk-dev IRC channels who may be able to assist you in testing, 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.

If you have submitted code in the past and are great at following the coding guidelines, then you may want to request access to Review Board. You can find the instructions for review board here. Code submitted to Review Board is likely to be included much faster than an untested patch just sitting in the tracker. The development team will provide access to Review Board for those that submit code often, write quality code and have a history of following the coding guidelines.

#### Who commits the code into Asterisk?

There are two ways code gets pushed into Asterisk.

1. Patches can always be merged by a member of the Asterisk Developer Community. Folks with commit access are those who have shown a willingness to work with the review process and are trusted shepherds of the project. Anyone with commit access can take ownership of a proposed patch and work to get it included in trunk - hence why the asterisk-dev mailing list is the best place to discuss patches.
2. Digium works through the queue of all issues on the tracker, both bugs and improvements. There's typically hundreds of issues in the backlog, including the work that the Asterisk Developer Community commits to at AstriDevCon every year. As such, we try to address as much as we can but there's no guarantee that we will get to any one issue.

#### What is the status of my issue?

The status of all issues in the tracker are reflected in the tracker. For any particular issue you'll want to look at the "Status" field and the comments tab under "Activity".

Status Field Value | Meaning
--- | ---
Triage | The issue has not been acknowledged yet. First a bug marshal needs to verify it's a valid report. Check the comments!
Open\Reopened | Issue has been acknowledged and is waiting for a developer to take it on. Typically we can't provide an ETA for development as priorities are complex and change constantly.
In Progress | A developer is working on this issue. Check the comments!
Waiting for Feedback | Check the comments. This issue is waiting on the "Assignee" to provide feedback needed for it to move forward. Once feedback is provided you need to click "Send Back".
Closed | Issue has been closed. Check the "Resolution" field for further information.
Complete | The intended resolution was reached, but additional tasks may remain before the issue can be completely closed out.

Watch an issue: You can receive E-mails whenever an issue is updated. You'll see a "watch" link on the actual JIRA issue, click that!

#### What's the deal with the clone of my issue (SWP-1234)?

You can safely ignore the issues starting with SWP. Digium has a whole group of developers dedicated to working on Asterisk open source issues. They use a separate project for internal time tracking to avoid cluttering up the main project. The clone being created does not indicate any particular status.

All comments, work, and anything of relevance to the patch or issue is done in the ASTERISK project

#### Why did my feature not make it into Asterisk?

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. 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 push it through, schedule time, etc.

## Digium Submission License Agreement

If you are going to contribute code to the Asterisk project, then please thoroughly read and then electronically sign the Digium Open Source Software Project Submission Agreement upon logging in to the Asterisk issue tracker. You'll see a "Sign a License Agreement" link at the top of the JIRA interface.

The gist of the agreement is that your contribution must not introduce any encumbrance to the Asterisk code base; Digium does not own your contribution, and they cannot take released Asterisk out of GPL. Relax; it's a very fair and reasonable license, 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 agreement once; it applies to all code that you send in via the issue tracker.

The issue tracker keeps a record of contributions and the license agreements that were in effect when those contributions were uploaded; it will currently restrict you from uploading a patch or documentation without a signed license agreement.

How to properly upload an attachment that requires a Submission License Agreement:

- When using the "Attach Files" form on a particular issue, be sure to select the "Yes, this is a code or documentation contribution" radio button.
- If you don't have a user license agreement, you'll see the message
  " You dont appear to have a current, signed submission license agreement on file. Please sign one before attempting to upload a code or documentation contribution."
- To sign a submission license agreement, use the "Sign a license Agreement" link at the top navigation bar in JIRA.
- The license agreement will be reviewed by Digium's legal department, then you'll be notified by E-mail of acceptance or rejection. If accepted you can now repeat the upload process and you'll be able to upload the code with a proper license associated to your account and showing by the attachment.

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 may have to delete your patch and ask you to re-upload it, properly marking it as a code submission so that your license will be associated.

## Get involved in Asterisk Development - influence the future of Asterisk

Reading the guidelines here is a great start! There are plenty of other wiki pages on Asterisk development which include coding guidelines. Feel free to start submitting relevant patches, documentation additions or fixes as soon as you can. There are many minor features and changes that need to be tested, reviewed and possibly expanded or tweaked before they can go into Asterisk.

Start associating with other Asterisk developers where they hang out http://www.asterisk.org/community/. You'll find them on primarily on IRC and the mailing lists. The forums are populated primarily by users.

Once you get to know the community and you really want to influence the Asterisk road-map, you'll want to check out AstriDevCon. AstriDevCon is an event held alongside AstriCon where the developers get together to review what was done in the past year and plan Asterisk's future.

## Attachments:

Selection_001.png (image/png)