이슈 및 토론 트리아지

이 가이드는 Quarto CLI GitHub 저장소의 이슈와 토론을 효과적으로 트리아지하기 위한 지침을 제공합니다. 주요 목표는 모든 이슈와 토론을 효율적으로 관리하여 명확하고 체계적인 프로젝트 워크플로를 유지하는 것입니다.

소개

목적

이 가이드는 Quarto CLI GitHub 저장소의 이슈와 토론을 효과적으로 트리아지하기 위한 지침을 제공합니다. 주요 목표는 모든 이슈와 토론을 효율적으로 관리하여 명확하고 체계적인 프로젝트 워크플로를 유지하는 것입니다.

범위

이 문서는 이슈와 토론을 식별, 검토, 관리하는 프로세스를 다룹니다. 여기에는 담당자 지정, 작업 우선순위 설정, 모든 이슈가 적절한 프로젝트 마일스톤으로 향하도록 하는 과정이 포함됩니다.

테크 리드 참여

테크 리드와 다른 유지관리자는 새로운 프로젝트 이슈의 지속적인 트리아지에 적극적으로 참여합니다. 이들의 참여는 프로젝트의 정돈 상태를 유지하고 이슈가 신속하고 효과적으로 처리되도록 하는 데 중요합니다.

이슈 정리

이슈는 명확한 Planning Horizon에 따라 지속적으로 마일스톤으로 정리됩니다. 이를 통해 팀은 프로젝트 진행 상황을 관리하고 이슈를 적시에 처리하기 위한 구조적인 접근을 갖게 됩니다.

Quarto CLI 저장소에서 모든 이슈와 토론 관리

팀 워크플로를 단순화하기 위해 모든 이슈는 여러 저장소로 분산하지 않고 quarto-cli 저장소에서만 관리하기로 결정했습니다. 예를 들어 quarto-web 문서 웹사이트와 관련된 이슈도 CLI 이슈가 아니더라도 quarto-cli 이슈에 등록합니다.

Planning Horizon

팀의 “Planning Horizon”은 다음 마일스톤까지로 제한합니다. 이 범위를 넘어서는 마일스톤으로 이슈를 트리아지하지 않습니다. 다음 마일스톤 이후의 모든 이슈는 “Future” 마일스톤으로 분류하여 팀의 작업량을 집중적이고 관리 가능하게 유지합니다.

마일스톤 의미 일정
Hot-fix 즉시 수정합니다. ASAP
현재 릴리스 적극적으로 작업 중입니다. 1-3개월
다음 릴리스 곧 작업할 예정입니다. 2-6개월
Future 언제/정말 작업할지는 모릅니다. 미정

이슈 트리아지

재현 가능성

  • 제시된 재현 단계에 따라 이슈를 재현합니다.
  • 이슈가 존재하는지 확인하고 필요한 경우 추가 정보를 수집합니다.

코멘트

  • 유익하고 존중하는 코멘트를 남깁니다.
  • 필요하면 추가 정보를 요청하고 명확한 가이드를 제공합니다.

식별

레이블

  • 이슈의 성격을 정의하기 위해 bug, enhancement, support, maintenance, documentation과 같은 명확하고 일관된 레이블을 사용합니다. 이슈는 이 레이블 중 정확히 하나를 가져야 합니다.
  • html, website, installers, crossref 등 유형에 따라 추가 레이블을 지정합니다.
  • 더 적절하게 분류하기 위해 필요한 경우 사용자 정의 레이블을 생성합니다.

우선순위 지정

배정 및 소유권

  • 전문성과 작업량을 고려해 적절한 팀원에게 이슈를 배정합니다(triaged-to 레이블 추가).

이슈가 배정되면 소유자가 지정됩니다. 소유자는 현재 이슈를 전진시키는 책임이 있는 사람입니다.

참고: 소유권은 해당 사람이 이슈를 직접 해결해야 한다거나 항상 적극적으로 작업 중이어야 한다는 뜻은 아닙니다.

triaged-to 레이블은 소유권을 다른 사람에게 재지정했음을 나타내기 위해 사용합니다.

  • 소유자가 취할 수 있는 건강한 행동:
    • 더 적절한 소유자로 재배정: 필요하다면 팀과 논의한 후 이슈를 가장 적합한 사람에게 배정합니다.
    • 더 적합한 마일스톤으로 트리아지: 필요 시 팀과 논의하여 더 관련성 높은 마일스톤으로 재배정합니다.
    • 이슈 재현 시도: 문제를 재현하여 추가 정보를 제공합니다.
    • 이슈 해결:
      • Close as completed: 이슈가 관련 PR로 해결되었습니다.
      • Close as not planned: 해결 계획이 없거나, 재현 불가(needs-repro 레이블)로 CI/CD에 의해 stale 처리되었거나, 실제로는 support/토론 이슈이거나, 더 이상 관련이 없는 경우입니다.
      • Close as duplicate: 다른 이슈의 중복입니다(duplicate).
  • 안티패턴 및 권장하지 않는 행동:
    • 소유자 해제: 모든 이슈에 지정 소유자가 있는 워크플로를 장려하므로 소유자를 제거하는 것은 권장하지 않습니다. 예외는 Future 마일스톤의 이슈로, 이 경우에는 소유자 지정이 덜 중요합니다.
    • 마일스톤 해제: 마일스톤을 제거하고 재지정하지 않으면 이슈는 사실상 미트리아지 상태가 됩니다. 이슈 마일스톤을 지속적으로 정제하는 것을 권장합니다.
    • 정보 없이 닫기: 명확한 설명이나 맥락 없이 이슈를 닫는 것은 권장하지 않습니다. 투명성과 이해를 위해 명확한 커뮤니케이션이 필수입니다.

소유자가 이슈를 전진시키는 데 장애물을 만날 수 있습니다. 추가 정보가 필요하거나 작업량을 재조정해야 할 수도 있습니다. 이런 경우 다음 행동을 권장합니다:

  • needs-discussion 레이블로 이슈 표시: 다음 팀 동기화에서 검토할 수 있도록 이 레이블을 지정합니다.
  • Slack으로 도움 요청: 팀 Slack 채널에 질문을 올려 즉시 도움이나 입력을 받습니다.

토론 트리아지

식별

카테고리

레이블

  • html, website, installers, crossref 등 유형에 따라 레이블을 지정합니다.

참여

  • 명확하고 존중하며 건설적인 의견으로 토론에 참여합니다.
  • 커뮤니티 참여를 장려하고 가치 있는 기여를 인정합니다.

재현 가능성

  • 사용자가 제시한 사용 사례를 재현하기 위한 단계를 따릅니다.
  • 필요하다면 추가 정보를 수집합니다.

코멘트

  • 유익하고 존중하는 코멘트를 남깁니다.
  • 필요하면 추가 정보를 요청하고 명확한 가이드를 제공합니다(Reply Templates 참고).

이슈로 승격

  • 토론이 버그 보고로 보이고 재현 가능하다면 Create issue from discussion GitHub 기능을 사용해 이슈로 변환합니다.
  • Close as outdated로 토론을 닫고 새로 생성한 이슈에 링크합니다.

해결

  • Q&A 토론의 경우, 아직 지정되지 않았다면 적절한 답변을 솔루션으로 표시합니다.
  • 이슈로 승격되지 않은 토론은 닫지 않습니다.

모범 사례

커뮤니케이션

  • 항상 명확하고 존중하는 커뮤니케이션을 유지합니다.
  • 간결하고 건설적인 피드백을 제공합니다.

일관성

  • 레이블, 마일스톤, 코멘트를 저장소 전체에서 일관되게 사용합니다.
  • 트리아지 관행을 정기적으로 검토하고 업데이트하여 효과를 유지합니다.

부록

템플릿

이슈 보고 템플릿

토론 템플릿

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/).