/
Bug Triager Guide – Suggestions & Tips 🐛

Bug Triager Guide – Suggestions & Tips 🐛

Overview  

Build-Test-Release (BTR) Working Group  

Bug Triagers are responsible for ensuring the proper use of the group's issue board and helping to resolve bugs in the system. They manage test reports, prioritize issues, and either resolve them or find appropriate resources to do so.

Suggested Practices for Bug Triagers

I (@Maria Grimaldi) put this document together to help you get started with the Bug Triager Role. Consider it a reference point, but keep in mind that it’s all from my perspective and experience!

Everyone has their own style, so don’t hesitate to adapt, tweak, or go a different route if it suits you better. The goal is for each of you to find what works best for you in the role. 

If you’re starting as a bug triager:

  1. Submit GH request so you get triage access to manage the necessary boards, here’s an example you can follow: [GH Request] Onboard DonatoBD · Issue #1150 · openedx/axim-engineering  

  2. Use this guide to familiarize yourself with the general flow, but don't feel you must follow every step rigidly.

Triaging Test Reports 

When a test report is filed in the BTR issues, the bug triager is responsible for the following:

  1. Find a Report to Triage

Go to the Test Failure Reports board and find an issue with the “needs triage” label.

  1. Review the Report

Review that the report contains all required information to reproduce the issue in a testing environment:

  • Review that the report contains all required fields. 

  • If any necessary information is missing, request additional details.  

  • If all fields are filled in the report, but you think there is not enough information to replicate the issue successfully, then request more details.

  1. Prioritize Based on the Community Testing Spreadsheet

Use the testing spreadsheet for the current release:  

  • Go to the spreadsheet for the release and search for the relevant test case ID.  

  • Once located, get the test priority from column L.  

  • If the report doesn’t include a test ID, search the test sheet using keywords to find a matching test case. Then, update the report title to include the correct test ID.

If you can’t find the issue in the Community Testing Spreadsheet, ask the Product Liaison for help prioritizing the report and add “No Test ID” to the title.

  • Once you get the priority, go to the reports board and fill the priority column to match.

You can also ask the product liaison for help on slack! 

  1.  Test the Issue  

Test the issue in the community remote environment and in the sandbox for the current release to verify if it’s reproducible:  

  • If it’s reproducible in both the current release and the community testing environment, then it’s a known issue.

  • If it’s reproducible only in the community testing environment for the release, then classify the issue as a regression.

Add a comment with what you found.

  1.  Further Investigation  

Gather more details about the issue:  

  • Review console logs and network request responses.  

  • Determine which repository in the Open edX codebase is affected.  

  • Check if the test failure has been reported previously, either in the issues board or on other platforms (Discourse, Slack, etc.).  

Add a comment with what you found.

  1. Transfer the Issue to the Corresponding Repository

Once the investigation is complete, transfer the issue to the relevant repository:

  • Make sure all the information gathered during triage is preserved in the transferred issue.

  • Tag the maintainers in the new repository to notify them of the problem.

  • Add the “release testing” label after the transfer (if not present).

  • Add the issue to the Build Test Release project in the new repository (if not present).

  • Check the issue was listed in the Release Testing Reports view.

  • Prioritize the issue according to the Priority column in the spreadsheet (see Step 3).

If you don’t have sufficient permissions to transfer the issue to the target repository, open an issue in axim-engineering and ask for help with the transfer.

  1. Remove the Needs Triage Label

Once you properly report the issue, you can remove the "needs triage" labels to let other bug triagers know its current status.

  1. Fix or Delegate the Issue

If you can fix the issue, assign it to yourself and work on the solution. If not, ask for assistance by sharing the issue in multiple channels (Discourse, Slack, etc.) to get help from the community. See the Help Fixing Issues section for more information.

All the information gathered during this phase will help the team discuss the issues, prioritize them, and eventually fix them.

Help Fixing Issues 

  1. Self-Assignment  

If you decide to work on an issue, assign it to yourself and leave comments on both the BTR failure report and the corresponding repository issue to inform others that you’re working on it.

  1.  Finding Help  

If you cannot fix the issue yourself, find someone who can assist you! You can:  

  • Create a list of unresolved issues.  

  • Post them in multiple community channels (e.g., Discourse, Slack) to ask for assistance.

  • Tag maintainers.

  • Post issues in #wg-maintainers seeking maintainer's attention or #core-contributors.

  • Mention them during the BTR weekly meeting.

  1. Backporting Fixes:  

Once a pull request (PR) that resolves an issue has been merged, ensure the fix is backported to the open-release/zabrawood.master branch either creating the backport yourself or asking the author for help. Tag the Release Manager in the backports you create or find.

  1. Update Community Test Spreadsheet

Once a solution has been merged and the issue has been closed, update the test status in the spreadsheet as Passed.

Bug Triagers don’t need to solve all issues reported during the Community Testing period, but at least this should happen before the major cut:

  • All blockers were resolved.

  • High priority issues have an owner and maintainers are aware. 

  • Medium priority issues were reported and maintainers are aware.

  • Low priority issues were reported.

Managing the BTR Board

  1. Timely Triage  

  All test reports must be triaged within 24 hours of being assigned.

  1. Repository Issues  

Ensure that each issue on the BTR board was transfered issue in the repository where the bug originated, and the issue shows in the BTR testing reports board.

  1. Status Updates 

When a PR is merged that resolves an issue, ensure the related issue is marked as "Closed"  

If work is still in progress on an issue, ensure the issue status is updated to "In Progress", and so on. Try leaving a comment so all parties are aware of the status.

  1. Regular Review 

Conduct a weekly review of the BTR board. Leave comments on open issues to update the status and ensure all issues are being actively managed.

  1. Escalation of Stale Issues

If any issue remains unresolved or stale for an extended period, escalate the issue by tagging the relevant maintainers, seeking support from the broader community or discussing them during a BTR meeting.

Join the BTR Weekly Meeting

The BTR working group meets once per week during the release testing, and Bug Triagers must be in attendance to:

  • Review the Release Testing Reports with the team (high-priority, medium, low).

  • Review whether to categorize high-priority reports as “release blockers” or not.

  • Ask for help to resolve open issues.