2024-02-01 New 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 processprocedure, this document will be updated.
...
Overview
Opening bug tickets at GitHub against FreePBX is a simple process.
...
This will open a form with several fields for adding information. Fields marked with a red asterisk are required to must be populated. Review the explanatory text and fill out the fields as requirednecesary. When finished, complete the submission by clicking the green “Submit new issue“ button
...
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 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 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 allowedThe 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.
...
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. If no information is provided and the reporter does not provide a timely response, the issue may be closed as invalid.
...