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.
| Table of Contents |
|---|
Overview
Open Opening bug tickets at GitHub against FreePBX is a simple process.
Open source FreePBX issues can be reported on GitHub at: http://issues.freepbx.org/ using the same account you have used to access all of the FreePBX EcoSystem.For commercial 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 the first business Monday following submissionregularly 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 all most issues, we must be able to reproduce the issue to fix it.Please do not ask for ETA's or timelines. If a developer has this information it will be passed along. Note all the information is contained in the ticket.
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 usedput in place, so that you (and everyone else) can see what the current status of your the ticket is.
Triage
This it the initial state all open source ticket start in. Once tickets are triaged they go into the open state. Ticket "triages" happen roughly every Monday. A ticket at this stage might be rejected if it's not a valid ticket
...
There are three actions a ticket can perform from Triage:
Approve: This will transition into the Open state
Reject: This will transition into the Closed state
Needs Information: This will transition into the Needs Information state
...
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.
...
There are three actions a ticket can perform from Needs Information:
Triage: This will move the ticket to the Triage state
No Information: This will move the ticket to the Closed state
Open: This will move the ticket to the Open state
...
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.
...
There are four actions a ticket can perform from Open:
In Review: This will move the ticket to the Dev Review state
Make New QA: This will move the ticket to the QA New state, skipping development
Start Progress: This will move the ticket to the In Progress state
Resolve Issue: This will move the ticket to the Resolved state (it is not closed)
...
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
...
There are three actions a ticket can perform from Dev Review:
Resolved: This will move the ticket to the Resolved state (it is not closed)
Start Progress: This will move the ticket to the In Progress state
Review to Reopened: This will move the ticket to the Open state
...
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.
...
There are five actions a ticket can perform from In Progress:
In Review: This will move the ticket to the Dev Review state
Resolve issue: This will move the ticket to the Resolved state (it is not closed)
Wait Progress: This will move the ticket to the Selected for Development state
Stop Progress: This will move the ticket to the On Hold state
Open: This will move the ticket to the Open state
...
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
...
There are two actions a ticket can perform from Selected for Development
Resolve Issue: This will move the ticket to the Resolved state (it is not closed)
Start Progress: This will move the ticket to the In Progress state
...
On Hold (Development State)
This means the ticket us in an indefinite hold.
...
There are two actions a ticket can perform from On Hold:
Resolve Issue: This will move the ticket to the Resolved state (it is not closed)
Start Progress: This will move the ticket to the In Progress state
...
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.
...
There are three actions a ticket can perform from On Hold:
Start QA Progress: This will move the ticket to the QA Progress state
Reopen Issue: This will move the ticket to the Open state
Close Issue: This will move the ticket to the Closed state
...
QA New (QA State)
This ticket is awaiting the start of the QA cycle. The ticket has skipped development completely.
...
There is one action a ticket can perform from QA New:
Start QA Progress: This will move the ticket to the QA Progress state
...
QA Progress (QA State)
The ticket is currently in progress as part of the QA cycle.
...
There are two actions a ticket can perform from QA New:
QA Review: This will move the ticket to the QA Review state
Reopen Issue: This will move the ticket to the Open state
...
QA Review (QA State)
The ticket is currently in review as part of the QA cycle.
...
There are three actions a ticket can perform from QA Review:
Close Issue: This will move the ticket to the Closed state
Reopen Issue: This will move the ticket to the Open state
Make New QA: This will move the ticket to the QA New state
...
Closed
The ticket has been closed. Comments are still allowed
...
There are two actions a ticket can perform from Closed
Admin Closed: This will move the ticket to the Admin Closed state
Retriage Issue: This will move the ticket to the Triage state
...
Admin Closed
The ticket has been closed and no comments are allowed
...
There is one action a ticket can perform from Admin Closed
Closed: This will move the ticket to the Closed state
...
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. Note IMPORTANT: the bug 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.
...
Unhandled exceptions such as "Whoops Errors" including what you did to make it happen.
Spelling and grammatic 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
...
Quality information is NOT:
100,000 line 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. It is critical you provide this in a timely manner. If no information is provided and the user reporter does not provide a timely response, the issue may be closed as invalid.
...
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://supporthelp.schmoozecomsangoma.com