Repository navigation
Investigation PR 가이드
edward edited this page Apr 25, 2026
·
1 revision
"조사도 머지 가능합니다." — rhwp 의 기여 패턴 중 하나입니다.
오픈소스 기여를 시작하면 종종 다음과 같은 상황을 만납니다:
- 이슈가 명확한데, 막상 들여다보니 한두 줄로 안 되고 엔진을 통째로 손봐야 할 것 같다
- 휴리스틱 몇 개를 시도해 봤지만 한 샘플에서는 좋아지고 다른 샘플에서는 나빠진다
- 진짜 원인은 알겠는데, 수정 범위가 부담스럽다
이런 상황에서 흔한 선택은 두 가지입니다:
- 포기하고 이슈를 닫지 않은 채 넘어간다 — 다른 사람이 같은 함정에 다시 빠진다
- 무리하게 큰 PR을 만들어 한 번에 해결한다 — 회귀 위험이 크고 리뷰가 어렵다
rhwp 에서는 세 번째 길 을 권장합니다.
다음과 같은 PR 도 충분히 머지 가치가 있습니다:
- 본 증상은 미해결 (이슈는 OPEN 유지)
- 그러나 원인 분석 결과, 시도한 휴리스틱과 그 결과, 검증 도구, 다음 단계 권고 가 들어 있음
- 코드 변경은 없거나, 회귀 위험 0 인 디버그 도구만 추가
이런 PR 을 머지하면 다음과 같은 효과가 있습니다:
| 차원 | 효과 |
|---|---|
| 조사 결과 보존 | 다른 기여자가 같은 함정 반복 안 함 |
| Epic 범위 축소 | 데이터 기반 결론으로 후속 작업 위험·비용 감소 |
| 검증 도구 활용 | 다음 작업자가 즉시 회귀 검증 가능 |
| 시간 절약 | 메인테이너가 매번 "어떻게 됐어요?" 묻지 않아도 됨 |
PR #308 은 이 패턴의 모범 사례입니다.
- 이슈 #306 ("페이지네이션 과잉, PDF 15쪽 vs SVG 19쪽") 을 조사
- 초기 가설 4개 모두 기각 (휴리스틱 실험 결과 명시 기록)
- 진짜 원인 발견: HWP 의 LINE_SEG
vpos=0리셋이 단/페이지 경계 신호인데 엔진이 무시하고 있음 - Epic #309 분리 권장 — "전면 재설계 필요" 결론
- 그러나 거기서 멈추지 않고, 검증 도구 (Task #310) 를 추가:
-
dump-pages에 vpos 정보 출력 -
--debug-overlay에 vpos=0 리셋 시각 표시
-
- 4 개 샘플 비교 분석으로 Epic 범위를 축소 (전면 재설계 → 단일 조건 분기)
PR 제목은 "수정 미완" 이지만:
- 이슈 #306: OPEN 유지 (정직 표기) — 본 증상은 미해결
- 이슈 #310: CLOSED — 진단 도구 등록 완료 (이 PR 의 핵심 산출물)
- Epic #309: 다음 단계가 "전면 재설계" 가 아닌 "단일 조건 분기" 로 축소
다음 작업자(메인테이너 또는 다른 기여자) 가 이 PR 을 기반으로 즉시 진입할 수 있게 되었습니다.
PR 제목에 "수정 미완", "조사", "spike" 같은 단어를 명시합니다. 본문에는:
- 어떤 가설을 시도했는가
- 각 가설의 검증 결과 (특히 기각된 가설)
- 기각 사유 (어떤 데이터를 보고 판단했는가)
- 진짜 원인 (가능하면 데이터로 증명)
- 다음 단계 권고
코드를 추가한다면:
- 옵트인 디버그 도구 (
--debug-overlay, 환경변수 등) - 진단 출력 보강 (CLI 옵션)
- 일반 사용자 동작에 영향 없음
엔진 자체를 만지지 않습니다. 본 작업은 다음 PR 에서 합니다.
조사 결과를 다음 위치에 저장합니다:
-
mydocs/working/task_m100_{번호}_analysis.md— 분석 보고서 -
mydocs/tech/{주제}_analysis.md— 영구 자료 (여러 타스크에서 참조 가능한 자료) -
mydocs/plans/task_m100_{번호}.md— 가설과 시도
- 본 증상 이슈: OPEN 유지 (조사로 해결되지 않음)
- 도구 등록 이슈: CLOSED (이 PR 로 등록 완료)
- Epic 이슈: OPEN, 다음 단계 권고 (있으면)
다음과 같은 경우에는 일반 PR 로 진행하시기 바랍니다:
- 본 증상이 1~2 줄 수정으로 해결되는 경우 — Investigation 단계 없이 바로 fix PR
- 다른 작업자에게 인계할 의사 없이 본인이 후속을 이어갈 계획인 경우 — 한 PR 로 완성
- 조사 결과를 메모만 남기고 머지하지 않을 의사가 강한 경우 — Issue 코멘트 또는 Discussion 활용
Investigation PR 을 거절할 때는 다음 기준을 검토합니다:
| 기준 | 통과 조건 |
|---|---|
| 조사 정직성 | 가설/실험/기각 사유가 명시되어 있는가 |
| 회귀 위험 | 일반 동작 변경 0 (옵트인 도구만) |
| 영구 자료 | 다른 기여자가 활용 가능한 형태로 보존되는가 |
| 다음 단계 명시 | Epic 또는 후속 이슈로 분리되어 있는가 |
| CI 통과 | 빌드/테스트/clippy 정상 |
이 기준을 통과하면 본 증상이 해결되지 않았더라도 머지 합니다.
- PR #308 — Task #306 조사 + Task #310 vpos 진단 도구 — Investigation PR 모범 사례
- Hyper-Waterfall 문서 체계 가이드 — rhwp 의 문서 구조 철학
- HWP 5.0 Spec Errata — 정오표 (외부 기여 항목 표기)
- HWP LINE_SEG vpos 이해 — PR #308 분석 결과 사용자 친화 버전