FreePBX Ticket Reporting
- Nathaniel Halbrooks
- Lorne Gaetz (Unlicensed)
In February of 2024, FreePBX Open Source bug ticket handling was moved to GitHub. Prior to that, tickets were handled in a Jira instance at https://issues.freepbx.org hosted by the FreePBX project.
The current GitHub reporting procedure is outlined herein. As work processes evolve using this new procedure, this document will be updated.
The policy described here is for non-security related bugs and issues. If you have a FreePBX Security issue to report, please see this page: Security Information
Overview
Opening bug tickets at GitHub against FreePBX is a simple process.
Open source FreePBX issues can be reported on GitHub at: https://github.com/FreePBX/issue-tracker/issues. GitHub user credentials are required to login.
For Commercial modules see: This Article
Commercial module tickets opened on the Open Source issue tracker will be closed and you will be forwarded to the above article.
How to Open a Ticket
Browse to https://github.com/FreePBX/issue-tracker/issues and click the green “New Issue” button:
From the screen that follow select the type of issue you wish to report, bug, feature, etc. by clicking the corresponding green “Get Started” button
This will open a form with several fields for adding information. Fields marked with a red asterisk must be populated. Review the explanatory text and fill out the fields as necesary. When finished, complete the submission by clicking the green “Submit new issue“ button
Expectations
Please note that tickets are handled through a triage system and may not be handled in the order received.
Our team monitors the bug tracker for blocker and show stopper issues but most tickets will be reviewed by members of the development team on regularly scheduled weekly triage meetings.
As part of the triage process, tickets will be moved from the issue-tracker project to the FreePBX module project to which it’s related. Links to the original ticket will be maintained.
Tickets may be resolved within minutes or it may take much longer. Please note a team member may change the priority - please do not change it back. The time it takes to resolve a ticket also depends on the effort required to resolve the issue. For most issues, we must be able to reproduce the issue to fix it.
Ticket Lifecycle
After a ticket is created, there is a workflow put in place, so that everyone can see what the current status of the ticket is.
The issue lifecycle stage is managed with “Labels” on GitHub. As the issues moves through the various lifecycle stages, it’s labels are updated to reflect the current status. Quick summary:
Lifecycle Stage | GitHub Label | Description |
|---|---|---|
Triage | All newly opened issues get the ‘triage’ label indicating that they are ready to be reviewed by the engineering team | |
Open | Once an issue has been triaged, before anything else is done, it’s moved to the ‘open’ stage. | |
In Progress | When an engineering team member is actively working on a ticket, the label changes to ‘in-progress’. | |
Dev Review | Code is committed to a branch and is ready for peer review | |
Resolved | Code is complete and changes have been merged. Marking the issue at this stage as ‘resolved’ indicates the merges are ready for QA. Code is published to the edge repo | |
Closed |
| Process is complete and code can be published to the stable repo. |
In addition to the lifecycle stage, there are also a handful of labels used to add a descriptive element to tickets to indicate the issue type.
Issue Type | GitHub Label | Description |
|---|---|---|
Bug | Issue describing a bug. | |
Improvement | Issue describing an improvement to an existing feature or functionality. | |
New Feature | Issue describing a new feature | |
Won’t Fix | Issue has been reviewed and deemed to be something that will not be fixed by Engineering. | |
Duplicate | Issue already exists | |
Needs | Issue requires additional information in order to progress, either from the original reporter, or someone else. |
Keeping your report alive
Bug issues may be closed for several reasons. It is important that you provide quality and timely information. IMPORTANT: the issue system is for bugs and is not for general questions, commentary or arbitrary discussion. If you are unsure that your issue is actually a bug, or are unable to describe it in a way that allows others to reproduce it, it is best to first discuss the issue in the forums at http://community.freepbx.org.
Things that should generally be reported as bugs:
Unhandled exceptions such as "Whoops Errors" including what you did to make it happen.
Spelling and grammatical errors.
Things that may be your browser, and should be tested in another browser or in the browsers safe/privacy mode:
Make sure you are running the latest updated version of your chosen browser. When filing browser based bugs ensure you provide the browser and OS along with versions.
Form fields auto filling (password fields and prior text input).
Javascript/Validation errors
Weird visual display
Missing Elements
Our team must be able to:
Understand what your actual issue is.
Reproduce the issue or see the issue clearly happening in logs.
To do this they need quality information.
Quality information is:
What is not working
What you expected it to do or not do
What it actually did or did not do
Relevant log sections (please obfuscate private information)
Relevant Call traces (please obfuscate private information)
Specific Version numbers
Specific Hardware models
Firmware and boot loader versions
Relevant configurations (please obfuscate private information)
Quality information is NOT:
Huge dumps of log files
Vague statements like "doesn't work", "I'm using FreePBX", “latest version”
If a ticket does not contain enough information a team member may ask you for more information. If no information is provided and the reporter does not provide a timely response, the issue may be closed as invalid.
Derivative works
If you are using FreePBX as part of a derivative project and have not obtained it directly from FreePBX it may be best to start with your project maintainer. They may modify FreePBX or restrict updates. Issues may already be fixed or may not exist except with their modifications. Some of these maintainers will file a bug with us as they know their modifications and can provide more information. Some maintain their own patches and may not stay fully up to date.
Support Request
Please note the bug system is not for general questions or support requests. If you think your issue may be configuration related please use the proper support channels. Bugs are items that affect more than one user with known good information. Bugs are typically items that can be reproduced by following a recipe.
Community Forum Support: http://community.freepbx.org
Paid Support: http://help.sangoma.com