Issue and Discussion Triage
This guide provides instructions for effectively triaging issues and discussions on Quarto CLI GitHub repository. The primary goal is to ensure that all issues and discussions are managed efficiently, helping maintain a clear and organized project workflow.
Introduction
Purpose
This guide provides instructions for effectively triaging issues and discussions on a Quarto CLI GitHub repository. The primary goal is to ensure that all issues and discussions are managed efficiently, helping maintain a clear and organized project workflow.
Scope
The document covers the processes for identifying, reviewing, and managing issues and discussions. This includes assigning responsibilities, prioritizing tasks, and ensuring all issues are directed towards the appropriate project milestones.
Tech Lead Engagement
Tech leads and other maintainers will be actively engaged in the ongoing triage of new project issues. Their involvement is crucial to maintaining the project’s organization and ensuring that issues are handled promptly and effectively.
Organization of Issues
Issues will be continuously organized into milestones based on a clear Planning Horizon. This ensures that the team has a structured approach to managing the project’s progress and addressing issues in a timely manner.
All Issues and Discussions Managed in Quarto CLI Repository
To simplify the team’s workflow, it has been decided that all issues will live in the quarto-cli
repository rather than being distributed across multiple repositories. For example, issues related to the quarto-web
documentation website will be logged in the quarto-cli
issues, even if they are not technically CLI issues.
Planning Horizon
The team’s “Planning Horizon” will be limited to the next Milestone. Issues will not be triaged to milestones beyond this Planning Horizon. All issues beyond the next Milestone will be triaged to the “Future” milestone, ensuring a focused and manageable workload for the team.
Milestone | Meaning | Timeline |
---|---|---|
Hot-fix | We will fix this right away. | ASAP |
Current Release | We are working on this actively. | 1-3 Months |
Next Release | We will work on this soon. | 2-6 Months |
Future | We don’t know when or if we will work on this. | Unclear |
Triaging Issues
Reproducibility
- Follow the steps provided to reproduce the issue.
- Confirm the issue exists and gather any additional information if needed.
Identification
Labels
- Use clear and consistent labels such as
bug
,enhancement
,support
,maintenance
, anddocumentation
to define the nature of the issue. Issues are expected to have exactly one of these labels. - Assign additional labels to categories issues based on their type such as
html
,website
,installers
,crossref
, etc. - Create custom labels if necessary to better categories issues.
Prioritization
- Assess the severity and impact of issues to determine priority, e.g.:
- use the
regression
label for bugs that appeared in a recent release - use the
Hot-fix
milestone or theFuture
milestone, see Planning Horizon. - use the number of reactions to the issue to gauge its importance to the community.
- use the
- Ensure a milestone is assigned to each issue to indicate its priority and expected completion date.
- Review the issues not assigned to a milestone and assign them accordingly.
Assignment and Ownership
- Assign issues to appropriate team members based on expertise and workload (add the
triaged-to
label).
When an issue is assigned, it is given an owner. The owner is the individual currently responsible for moving the issue forward.
Note: Ownership does not imply that the person must resolve the issue themselves or be actively working on it at all times.
The triaged-to
label is used when assigning ownership to indicate that an issue has been reassigned to someone else.
- Healthy actions taken by the owner include:
- Re-assigning to a more appropriate owner: This can be done, sometimes after consulting with the team, to ensure the issue is handled by the most suitable person.
- Triaging to a better Milestone: Reassessing and assigning the issue to a more relevant Milestone, again, sometimes after team consultation.
- Attempting to reproduce the issue: Providing more information by trying to replicate the issue.
- Resolving the issue:
- Close as completed: The issue has been resolved with a pull request linked to the issue.
- Close as not planned: The issue is not planned to be resolved, was marked by CI/CD as
stale
because of a lack of reproducibility (needs-repro
label), is actually asupport
/ discussion issue, or is no longer relevant. - Close as duplicate: The issue is a duplicate of another issue (
duplicate
).
- Anti-patterns and discouraged actions:
- Un-assigning the owner: Making the issue ownerless is discouraged as we promote a workflow where every issue has a designated owner. The exception to this rule is for issues in the Future milestone, where having assigned owners is less critical.
- Un-assigning the milestone: Removing the milestone from an issue without reassigning it effectively un-triages it. We promote continuous refinement of issue milestones.
- Closing without information: Closing issues without providing a clear explanation or context is discouraged. Clear communication is essential for maintaining transparency and understanding.
An owner might encounter obstacles that prevent them from moving an issue forward. They might need additional information or need to re-balance their workload. In such cases, we encourage the following actions:
- Flag the issue with
needs-discussion
: Mark the issue with this label so it can be reviewed at the next team sync. - Seek help via Slack: Post a question in the team Slack channel to get immediate assistance or input from team members.
Triaging Discussions
Identification
Categories
- Ensure discussions are categorized based on their nature, such as
Features Requests
,Q&A
, andShow and tell
.
Labels
- Assign labels to categorize issues based on their type such as
html
,website
,installers
,crossref
, etc.
Participation
- Engage in discussions with clear, respectful, and constructive input.
- Encourage community involvement and acknowledge valuable contributions.
Reproducibility
- Follow the steps provided to reproduce the user’s use case.
- Gather any additional information if needed.
Comments
- Leave informative and respectful comments.
- Ask for additional details if needed and provide clear guidance (see Reply Templates).
Upgrading to Issues
- If a discussion appears to be a bug report and can be reproduced, use Create issue from discussion GitHub feature to convert it into an issue.
- Close as outdated the discussion and link to the newly created issue.
Resolution
- For
Q&A
discussions, mark the appropriate answer as the solution if not done already. - Do not close discussions unless it has been upgraded to an issue.
Best Practices
Communication
- Maintain clear and respectful communication at all times.
- Provide concise and constructive feedback.
Consistency
- Ensure labels, milestones, and comments are used consistently across the repository.
- Regularly review and update triaging practices to maintain effectiveness.
Comments