빠른 구조
repo/
├─ .github/
│ ├─ ISSUE_TEMPLATE/
│ │ ├─ bug_report.md
│ │ └─ feature_request.yml
│ └─ pull_request_template.md
└─ docs/
└─ PULL_REQUEST_TEMPLATE/
└─ release.md| 파일 | 역할 |
|---|---|
.github/ISSUE_TEMPLATE/*.md | Markdown issue template |
.github/ISSUE_TEMPLATE/*.yml | 구조화된 issue form |
.github/pull_request_template.md | 기본 PR template |
PULL_REQUEST_TEMPLATE/*.md | 여러 PR template |
구조 기준
Issue template은 새 이슈를 열 때 필요한 정보를 빠뜨리지 않게 만드는 문서입니다. Markdown template은 본문에 그대로 들어갈 안내와 체크리스트를 작성하는 방식이고, issue form은 YAML schema로 입력 필드와 required 여부를 정의하는 방식입니다.
---
name: Bug report
about: Report a reproducible bug
title: "[BUG] "
labels: bug
---
재현 절차:
1. [첫 단계]
2. [두 번째 단계]
3. [확인 결과]Issue form은 사용자가 웹 form을 채우면 결과가 표준 Markdown issue body로 변환됩니다. 입력을 구조화해야 하거나 필수 항목을 강제해야 한다면 Markdown template보다 issue form이 더 적합합니다.
PR template은 PR 본문을 표준화합니다. 변경 요약, 테스트 결과, 관련 이슈, 배포 영향 같은 항목을 미리 넣어 두면 리뷰어가 확인해야 할 정보가 안정적으로 모입니다.
선택 기준
| 상황 | 선택 |
|---|---|
| 자유로운 설명과 체크리스트 | Markdown issue template |
| 필수 입력, dropdown, checkbox 필요 | YAML issue form |
| 모든 PR에 같은 확인 항목 적용 | 기본 PR template |
| 변경 유형별 PR template 필요 | PULL_REQUEST_TEMPLATE/ 하위 template |
| 조직 전체 기본값 필요 | default community health file 검토 |
| template이 보이지 않음 | default branch 위치와 파일 확장자 확인 |
Template은 협업 규칙을 문서화하는 동시에 입력 품질을 높이는 장치입니다. 너무 많은 질문을 넣으면 작성자가 template을 지우고 제출할 수 있으므로, 실제 리뷰나 triage에 쓰는 항목만 남기는 편이 좋습니다.
주의할 점
Issue와 PR template은 저장소 default branch에 있어야 동작합니다. 다른 branch에만 추가하면 collaborators가 새 이슈나 PR을 만들 때 template을 보지 못할 수 있습니다.
Markdown issue template과 YAML issue form은 목적이 다릅니다. 구조화된 입력이 필요한데 Markdown template만 쓰면 누락을 막기 어렵고, 자유 설명이 중요한데 form을 과하게 쓰면 맥락이 잘릴 수 있습니다.
참고 링크
2 sources