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.

Comments

  • Leave informative and respectful comments.
  • Ask for additional details if needed and provide clear guidance.

Identification

Labels

  • Use clear and consistent labels such as bug, enhancement, support, maintenance, and documentation 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

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 a support / 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

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.

Appendix

Templates

Issue Reporting Template

Discussion Template

Reply Templates

Code of Conduct

> [!IMPORTANT]
> We appreciate your interest in the Quarto project, but the content above violates our [Code of Conduct](https://github.com/quarto-dev/quarto-cli?tab=coc-ov-file#readme).
>
> As a member of the Quarto community, you are expected to follow our Code of Conduct, which outlines the standards of behavior and communication that we value. The Code of Conduct applies to all online interactions within the Quarto project, and it is enforced by the Quarto team. By participating in the Quarto community, you agree to abide by the Code of Conduct and respect the rights and dignity of others. You can find the Code of Conduct at <https://github.com/quarto-dev/quarto-cli?tab=coc-ov-file#readme>.
> 
> Thank you for your cooperation and contribution. 🙏

Ask reformat

Could you properly format your post using code blocks for code and terminal outputs? Thanks.
If your code contains code blocks, you need to enclose it using more backticks, *i.e.*, usually four ` ```` `.
See <https://quarto.org/bug-reports.html#formatting-make-githubs-markdown-work-for-us>.

Ask reproducible example

Could you share a **small self-contained "working" (reproducible)** example to work with, _i.e._, a complete Quarto document or a Git repository? The goal is to make it as easy as possible for us to recreate your problem so that we can fix it: please help us help you! Thanks.

---

You can share a **self-contained "working" (reproducible)** Quarto document using the following syntax, _i.e._, using more backticks than you have in your document (usually four ` ```` `).
See <https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines>.

If you have multiple files (and if it is **absolutely required** to have multiple files), please share as a Git repository.

<table>
<tr><th>R</th><th>Python</th></tr>
<tr><td>

`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a reproducible Quarto document.

{{< lipsum 1 >}}

```{r}
x <- c(1, 2, 3, 4, 5)
y <- c(1, 4, 9, 16, 25)

plot(x, y)
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

The end after @fig-placeholder.
````
`````

</td><td>

`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: jupyter
---

This is a reproducible Quarto document.

{{< lipsum 1 >}}

```{python}
import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [1, 4, 9, 16, 25]

plt.plot(x, y)
plt.show()
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

The end after @fig-placeholder.
````
`````

</td></tr>
</table>

Additionally and if not already given, please share the output of `quarto check` within a code block (*i.e.*, using three backticks ` ```txt `), see <https://quarto.org/bug-reports.html#check>.

Reproducible example

---

You can share a **self-contained "working" (reproducible)** Quarto document using the following syntax, _i.e._, using more backticks than you have in your document (usually four ` ```` `).
See <https://quarto.org/bug-reports.html#small-is-beautiful-aim-for-a-single-document-with-10-lines>.

If you have multiple files (and if it is **absolutely required** to have multiple files), please share as a Git repository.

<table>
<tr><th>R</th><th>Python</th></tr>
<tr><td>

`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: knitr
---

This is a reproducible Quarto document.

{{< lipsum 1 >}}

```{r}
x <- c(1, 2, 3, 4, 5)
y <- c(1, 4, 9, 16, 25)

plot(x, y)
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

The end after @fig-placeholder.
````
`````

</td><td>

`````md
````qmd
---
title: "Reproducible Quarto Document"
format: html
engine: jupyter
---

This is a reproducible Quarto document.

{{< lipsum 1 >}}

```{python}
import matplotlib.pyplot as plt

x = [1, 2, 3, 4, 5]
y = [1, 4, 9, 16, 25]

plt.plot(x, y)
plt.show()
```

![An image]({{< placeholder 600 400 >}}){#fig-placeholder}

{{< lipsum 1 >}}

The end after @fig-placeholder.
````
`````

</td></tr>
</table>

Additionally and if not already given, please share the output of `quarto check` within a code block (*i.e.*, using three backticks ` ```txt `), see <https://quarto.org/bug-reports.html#check>.

Accessibility: descriptive link text

Accessibility: For better accessibility, please ensure link text is descriptive and meaningful rather than using generic terms such as "here". This helps all users understand the link's destination. See [Writing meaningful link text (WCAG)](https://www.wcag.com/blog/writing-meaningful-link-text/).

Accessibility: alternative text

Accessibility: To improve accessibility, please add alternative text to your screenshots. This helps all users, including those using screen readers, to understand the context of the images. A brief description can make a big difference! See [Good Alt Text, Bad Alt Text — Making Your Content Perceivable](https://www.wcag.com/blog/good-alt-text-bad-alt-text-making-your-content-perceivable/).