Merge pull request #1527 from mcanouil/docs/triaging-guide

docs: Add issue and discussion triage guide documentation

Author: cderv

docs/triaging/index.qmd

@@ -0,0 +1,377 @@
+---
+title: "Issue and Discussion Triage"
+description: |
+  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.
+engine: markdown
+toc-depth: 4
+---
+
+## 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](#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`](https://github.com/quarto-dev/quarto-cli) repository rather than being distributed across multiple repositories.
+For example, issues related to the [`quarto-web`](https://github.com/quarto-dev/quarto-web) documentation website will be logged in the [`quarto-cli`](https://github.com/quarto-dev/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](https://github.com/quarto-dev/quarto-cli/milestone/7) | 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](https://github.com/quarto-dev/quarto-cli/milestone/2)  | We don't know when or if we will work on this. | Unclear    |
+
+{{< pagebreak >}}
+
+## 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`](https://github.com/quarto-dev/quarto-cli/labels/bug), [`enhancement`](https://github.com/quarto-dev/quarto-cli/labels/enhancement), [`support`](https://github.com/quarto-dev/quarto-cli/labels/support), [`maintenance`](https://github.com/quarto-dev/quarto-cli/labels/maintenance), and [`documentation`](https://github.com/quarto-dev/quarto-cli/labels/documentation) to define the nature of the issue.
+  Issues are expected to have exactly one of these labels.
+- Assign additional [labels](https://github.com/quarto-dev/quarto-cli/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](https://github.com/quarto-dev/quarto-cli/labels/regression) for bugs that appeared in a recent release
+  - use the [`Hot-fix` milestone](https://github.com/quarto-dev/quarto-cli/milestone/7) or the [`Future` milestone](https://github.com/quarto-dev/quarto-cli/milestone/2), see [Planning Horizon](#planning-horizon).
+  - use the number of reactions to the issue to gauge its importance to the community.
+- Ensure a milestone is assigned to each issue to indicate its priority and expected completion date.
+  - Review the [issues not assigned to a milestone](https://github.com/quarto-dev/quarto-cli/issues?q=is%3Aissue%20state%3Aopen%20no%3Amilestone) and assign them accordingly.
+
+### Assignment and Ownership
+
+- Assign issues to appropriate team members based on expertise and workload (add the [`triaged-to` label](https://github.com/quarto-dev/quarto-cli/labels/triaged-to)).
+
+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](https://github.com/quarto-dev/quarto-cli/labels/triaged-to) 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*]{.badge .rounded-pill .text-bg-primary}: The issue has been resolved with a pull request linked to the issue.
+    - [*Close as not planned*]{.badge .rounded-pill .text-bg-primary}: The issue is not planned to be resolved, was marked by CI/CD as [`stale`](https://github.com/quarto-dev/quarto-cli/labels/stale) because of a lack of reproducibility ([`needs-repro` label](https://github.com/quarto-dev/quarto-cli/labels/needs-repro)), is actually a [`support`](https://github.com/quarto-dev/quarto-cli/labels/support) / discussion issue, or is no longer relevant.
+    - [*Close as duplicate*]{.badge .rounded-pill .text-bg-primary}: The issue is a duplicate of another issue ([`duplicate`](https://github.com/quarto-dev/quarto-cli/labels/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`](https://github.com/quarto-dev/quarto-cli/labels/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.
+
+{{< pagebreak >}}
+
+## Triaging Discussions
+
+### Identification
+
+#### Categories
+
+- Ensure discussions are categorized based on their nature, such as [`Features Requests`](https://github.com/quarto-dev/quarto-cli/discussions/categories/feature-requests), [`Q&A`](https://github.com/quarto-dev/quarto-cli/discussions/categories/q-a), and [`Show and tell`](https://github.com/quarto-dev/quarto-cli/discussions/categories/show-and-tell).
+
+#### Labels
+
+- Assign [labels](https://github.com/quarto-dev/quarto-cli/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](#reply-templates)).
+
+### Upgrading to Issues
+
+- If a discussion appears to be a bug report and can be reproduced, use [*Create issue from discussion*]{.badge .rounded-pill .text-bg-primary} GitHub feature to convert it into an issue.
+- [*Close as outdated*]{.badge .rounded-pill .text-bg-primary} the discussion and link to the newly created issue.
+
+### Resolution
+
+- For [`Q&A` discussions](https://github.com/quarto-dev/quarto-cli/discussions/categories/q-a), mark the appropriate answer as the solution if not done already.
+- Do not close discussions unless it has been upgraded to an issue.
+
+{{< pagebreak >}}
+
+## 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.
+
+{{< pagebreak >}}
+
+## Appendix
+
+### Templates
+
+#### Issue Reporting Template
+
+- [Bug report](https://github.com/quarto-dev/quarto-cli/tree/main/.github/ISSUE_TEMPLATE/bug_report.yml)
+- [Documentation issue](https://github.com/quarto-dev/quarto-cli/blob/main/.github/ISSUE_TEMPLATE/documentation.yml)
+
+#### Discussion Template
+
+- [Feature Requests](https://github.com/quarto-dev/quarto-cli/blob/main/.github/DISCUSSION_TEMPLATE/feature-requests.yml)
+- [Q&A](https://github.com/quarto-dev/quarto-cli/blob/main/.github/DISCUSSION_TEMPLATE/q-a.yml)
+- [Show and Tell](https://github.com/quarto-dev/quarto-cli/blob/main/.github/DISCUSSION_TEMPLATE/show-and-tell.yml)
+
+### Reply Templates
+
+#### Code of Conduct
+
+````{.markdown shortcodes=false}
+> [!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
+
+````{.markdown shortcodes=false}
+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
+
+``````{.markdown shortcodes=false}
+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
+
+``````{.markdown shortcodes=false}
+---
+
+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
+
+````{.markdown shortcodes=false}
+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
+
+````{.markdown shortcodes=false}
+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/).
+````