오픈소스 기여자를 위해 더 나은 GitHub 이슈를 작성하면서 배운 점
Source: Dev.to
오픈소스 프로젝트를 유지보수하면서 예상치 못한 것을 배웠다: 좋은 GitHub 이슈를 작성하는 것 자체가 하나의 스킬이라는 점이다. 초반에는 내가 이슈를 이해하면 기여자들도 이해할 것이라고 생각했다. 실제로는 그렇지 않은 경우가 드물다. 기여자들은 새로운 시각으로, 제한된 맥락과 거의 없는 모호함에 대한 인내심으로 이슈를 본다.
최근에는 의도적으로 이슈 작성 방식을 개선하고 스스로에게 간단한 질문을 던졌다: “만약 내가 처음 보는 기여자라면, 이 이슈를 보고 어디서 시작해야 할지 알 수 있을까?”
다음은 이슈의 명확성을 높이고 기여자 친화적으로 만들기 위해 도움이 된 몇 가지 교훈이다.
왜 이슈 품질이 생각보다 중요한가
기여자의 관점에서 이슈는 보통 1분 이내에 평가된다. 그들은 다음을 살핀다:
- 문제가 명확히 서술되어 있는가?
- 범위가 합리적인가?
- “완료”가 무엇인지 명확한가?
- 어느 부분의 코드베이스와 연관되는지 알 수 있는가?
이 중 하나라도 불분명하면, 많은 기여자들은 프로젝트를 좋아하더라도 그냥 넘어간다.
유지보수자 입장에서는 불명확한 이슈가 다음을 초래한다:
- 의도를 명확히 하기 위한 긴 댓글 스레드
- 기대치 불일치
- 포기된 PR
명확한 이슈는 양쪽 모두의 시간을 절약한다.
내가 이슈를 작성하는 방식을 바꾼 점
1. 컨텍스트와 작업을 분리
이제는 기여자들이 바로 실행 가능한 부분을 찾을 수 있도록 이슈를 구조화한다. 일반적인 흐름:
- 문제 / 현재 상황
- 왜 중요한가
- 무엇을 바꿔야 하는가
- 수용 기준
이렇게 하면 독자들이 텍스트 벽을 읽는 대신 스마트하게 스킴할 수 있다.
2. “완료”를 명시적으로 표시
가장 큰 개선점 중 하나는 수용 기준을 구체적으로 적는 것이었다.
예전:
“지불 파이프라인 정리”
현재는:
- 레거시 경로 제거
- 하나의 정규 흐름만 남김
- 테스트 업데이트
- 동작 회귀 없음
기여자는 작업이 언제 완료됐는지 추측할 필요가 없어야 한다.
3. 코드베이스 친숙함을 가정하지 않기
경험 많은 개발자라도 당신의 코드에 처음일 수 있다. 도움이 되는 추가 사항:
- 관련 모듈 명시
- 진입점 언급
- 기존 명령어나 테스트에 대한 링크 제공
이렇게 하면 시작하는 데 드는 정신적 비용이 낮아진다.
예시 이슈
이 아이디어를 적용해 작성한 이슈 하나를 보여준다:
👉
수정을 요청하기 위해 공유하는 것이 아니라, 다음과 같이 실제 예시를 보여주기 위해 공유한다:
- 현재 상태 설명
- 목표 설명
- 수용 기준 정의
- 기여자를 위한 모호성 감소
OSS 프로젝트를 유지보수한다면, 이런 구조가 도움이 될 이슈들을 본 적이 있거나 직접 작성했을 것이다. 아직도 잘 하는 방법을 배우는 중이지만, 이슈 작성을 더 의도적으로 하게 된 이후:
- 기여자들이 참여하기가 쉬워졌다
오픈소스 프로젝트를 유지보수한다면, 궁금한 점:
- 어떤 요소가 GitHub 이슈를 당신에게 실행 가능하게 만든다고 생각하나요?
- 유지보수자들이 가장 흔히 저지르는 실수는 무엇인가요?