2024-02-01 New GitHub reporting procedure is outlined herein. As work processes evolve using this new process, this document will be updated.
Overview
Opening bug tickets 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 are required to be populated. Review the explanatory text and fill out the fields as required. 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.
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
As processes change and improve these states and the ticket life cycle may be updated
After a ticket is created, there is a workflow that is used, so that you (and everyone else) can see what the status of your ticket is.
Triage
This it the initial state that all open source tickets start in. Once tickets are triaged during our weekly review meetings, they may go into the open state or you may be requested to include additional information. A ticket may be rejected at the triage stage if it’s determined not to be a valid ticket.
Needs Information
When you see the Status as NEEDS INFORMATION that means the ticket is awaiting a response from the original submitter. If there is no reply within two weeks time the ticket will automatically close. It may be reopened it if you can supply the needed feedback.
Open (Development State)
This is the state a ticket reaches right after triage. It may or may not be assigned to a developer. Any bug in the Open status is considered as a new bug. If it has been assigned to a developer, it means that the developer has been allocated this bug as part of the Triage process. Another developer may take this bug, if they want. If another developer wishes to work on that bug, they should contact the developer who is currently assigned to this ticket.
Dev Review (Development State)
This state was formerly called "In Review". Several states also call this "In Review" as a transition. A ticket should be in this state if there is an active Pull Request Waiting to be merged
In Progress (Development State)
When the Status is set to IN PROGRESS that means the team member has added it into their current work queue. Note developers may be actively working on multiple projects or issues. This state may last minutes or weeks depending on the issue.
Selected for Development (Development State)
This means the ticket has been selected for development but is not currently in progress. It should be in progress shortly
On Hold (Development State)
This means the ticket us in an indefinite hold.
Resolved (QA State)
This means the ticket has finished the development cycle and is now awaiting the QA cycle. The ticket is finished from the developer's point of view.
QA New (QA State)
This ticket is awaiting the start of the QA cycle. The ticket has skipped development completely.
QA Progress (QA State)
The ticket is currently in progress as part of the QA cycle.
QA Review (QA State)
The ticket is currently in review as part of the QA cycle.
Closed
The ticket has been closed. Comments are still allowed
Admin Closed
The ticket has been closed and no comments are allowed
Keeping your report alive
Bug issues may be closed for several reasons. It is important that you provide quality and timely information. Note the bug 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:
100,000 line log files
Vague statements like "doesn't work", "I'm using FreePBX"
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