효과적인 Issue 리포트와 PR 제출 방법

버그를 발견했는데 어떻게 설명해야 할지 막막한 적 있으시죠? 내용을 모호하게 적으면 메인테이너가 다시 질문을 던지게 되고, 결국 문제를 해결하기까지 불필요한 시간이 흐르게 됩니다. 서로의 시간을 아끼고 버그를 빠르게 잡을 수 있는 Issue 작성법을 정리해 드릴게요.

필요한 것

Issue를 작성하기 전에 아래 항목들을 미리 준비해 주세요.

• GitHub와 codebase에서 기존 Issue가 있는지 검색
• 보안 관련 이슈가 최근에 해결되었는지 확인
• 재현 단계와 이를 증명할 증거 (로그, 스크린샷)
• OS, runtime, 버전, 설정 등 환경 정보

빠른 시작

최소한의 노력으로 최대의 효과를 내는 Issue 작성 방법입니다. 5분 안에 작성을 끝내보세요.

1. 제목 작성: 문제 발생 영역과 증상을 명확하게 적어주세요.
2. 최소 재현 단계: 문제를 일으키는 가장 짧은 경로를 설명하세요.
3. 기대 결과 vs 실제 결과: 무엇을 예상했고, 실제로 어떤 일이 일어났는지 비교해 주세요.
4. 환경 정보: 사용 중인 OS와 runtime 버전을 포함하세요.
5. ** lobster-biscuit**: Issue 내용에 이 코드 워드를 반드시 포함해야 합니다.

문제 해결

PR을 제출하기 전이나 Issue를 올리기 전에 아래 명령어를 실행해서 로컬에서 먼저 검증해 보세요.

• pnpm lint
• pnpm check
• pnpm build
• pnpm test
• 프로토콜 코드를 수정했다면: pnpm protocol:check

Issue Templates

상황에 맞는 템플릿을 복사해서 사용하세요.

Bug report

- [ ] Minimal repro
- [ ] Expected vs actual
- [ ] Environment
- [ ] Affected channels, where not seen
- [ ] Logs/screenshots (redacted)
- [ ] Impact/severity
- [ ] Workarounds

### Summary

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

### Workarounds

Security issue

보안 이슈의 경우 공개적인 장소에 상세한 공격 방법을 적지 마세요. 내용을 최소화하고 비공개 공개를 요청해 주세요.

### Summary

### Impact

### Versions

### Repro Steps (safe to share)

### Mitigation/workaround

### Evidence (redacted)

Regression report

### Summary

### Last Known Good

### First Known Bad

### Repro Steps

### Expected

### Actual

### Environment

### Logs/Evidence

### Impact

Feature request

### Summary

### Problem

### Proposed Solution

### Alternatives

### Impact

### Evidence/examples

Enhancement

### Summary

### Current vs Desired Behavior

### Rationale

### Alternatives

### Evidence/examples

Investigation

### Summary

### Symptoms

### What Was Tried

### Environment

### Logs/Evidence

### Impact

Submitting a fix PR

PR을 올리기 전에 Issue를 미리 만드는 것은 선택사항입니다. Issue 없이 PR을 올린다면 상세 내용을 PR에 직접 적어주세요. PR은 수정하려는 핵심 내용에 집중해야 합니다. Issue 번호를 명시하고, 테스트를 추가하거나 테스트가 없는 이유를 설명해 주세요. 동작 변경 사항이나 리스크를 기록하고, 증거로 활용할 로그나 스크린샷을 포함한 뒤 위에서 언급한 validation 과정을 거쳐 제출해 주세요.

궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Contributing Guidelines
• Code of Conduct