오픈소스에 기여하는 실전 가이드 — 첫 PR부터 메인테이너까지
Good First Issue 찾기, Fork→Branch→PR 플로우, 코드 리뷰 대응법.
한 줄 요약: 오픈소스 기여는 "Good First Issue" 찾기부터 시작해 Fork → Branch → PR → 코드 리뷰 대응의 흐름을 따른다. 첫 PR을 통과시키는 것이 가장 어려운 단계이고, 이후는 반복하면 된다.
오픈소스 기여를 막는 가장 큰 심리적 장벽은 "내 코드가 충분히 좋지 않다"는 생각이다. 하지만 실제로 대부분의 프로젝트가 원하는 기여는 문서 수정, 오타 수정, 재현 스크립트 작성, 번역처럼 코딩 실력보다 꼼꼼함과 커뮤니케이션 능력이 더 중요한 작업들이다. 이 글은 첫 PR을 성공적으로 통과시키는 방법부터 시작해, 메인테이너로 성장하는 경로까지 단계별로 설명한다.
Good First Issue 찾는 법
무작정 대형 프로젝트의 코드베이스를 열어 기여할 곳을 찾으려 하면 압도된다. 올바른 시작점은 "Good First Issue" 레이블이 붙은 이슈다.
GitHub에서 Good First Issue 찾기
GitHub에서는 label:"good first issue" 필터로 전체 GitHub에서 검색할 수 있다. 관심 있는 언어나 토픽을 함께 필터링하면 된다.
- github.com/issues — Good First Issue 필터
- goodfirstissue.dev — 언어별로 큐레이션된 Good First Issue 모음
- up-for-grabs.net — 태그별 오픈소스 이슈 검색
좋은 첫 이슈의 조건
- 스코프가 명확하다: "이 함수의 반환 타입 추론이 잘못됐습니다"처럼 무엇을 고쳐야 하는지 구체적으로 서술된 이슈
- 재현 방법이 있다: 재현 스크립트나 스텝이 이미 이슈에 작성된 경우
- 메인테이너가 응답한다: 이슈에 메인테이너 댓글이 있고 최근 활성화된 프로젝트인지 확인
- PR이 이미 없다: 이슈에 "I'm working on this" 댓글이나 연결된 PR이 없는지 확인
이슈를 선택한 후 첫 댓글
기여하기로 결정했다면 이슈에 먼저 댓글을 남겨라. "I'd like to work on this. Can I be assigned?" 또는 "접근 방식을 먼저 공유하고 피드백을 받겠습니다"처럼. 이미 누군가 작업 중인 이슈에 PR을 보내는 것은 중복 작업이고, 메인테이너 입장에서도 곤란하다.
Fork → Branch → PR 기본 플로우
실제 기여 작업의 Git 플로우를 단계별로 설명한다.
오픈소스 기여 Git 워크플로우# 1. 원본 저장소를 GitHub에서 Fork (UI에서 Fork 버튼 클릭) # 2. 내 Fork를 로컬에 클론 git clone https://github.com/MY_USERNAME/REPO_NAME.git cd REPO_NAME # 3. 원본 저장소를 upstream으로 추가 git remote add upstream https://github.com/ORIGINAL_OWNER/REPO_NAME.git # 4. 원본의 최신 상태를 가져와서 로컬 main을 최신으로 유지 git fetch upstream git checkout main git merge upstream/main # 5. 작업할 브랜치 생성 (이슈 번호 또는 설명적인 이름 사용) git checkout -b fix/issue-123-null-check # 또는 git checkout -b feat/add-timeout-option # 6. 코드 수정 후 커밋 git add -p # 변경 사항을 hunk 단위로 선택적으로 스테이징 git commit -m "fix: handle null return value in parseConfig (#123)" # 7. 내 Fork에 푸시 git push origin fix/issue-123-null-check # 8. GitHub에서 PR 생성 (푸시 후 GitHub UI에서 'Compare & pull request' 버튼) # 9. PR 머지 후 브랜치 정리 git checkout main git fetch upstream git merge upstream/main git branch -d fix/issue-123-null-check git push origin --delete fix/issue-123-null-check
커밋 컨벤션과 PR 작성 요령
Conventional Commits
대부분의 활성 오픈소스 프로젝트는 Conventional Commits 규격을 따른다. 형식은 다음과 같다.
<type>[optional scope]: <description>
fix:버그 수정feat:새 기능 추가docs:문서 수정refactor:기능 변경 없는 코드 구조 변경test:테스트 추가/수정chore:빌드 도구, 의존성 등 기타 변경
예: fix(parser): handle undefined token in parseExpression
PR 설명 잘 쓰는 법
메인테이너는 하루에 여러 PR을 검토한다. PR 설명이 부실하면 검토 우선순위에서 밀린다. 좋은 PR 설명의 구조:
- What: 무엇을 변경했는가 (1~3줄 요약)
- Why: 왜 이 변경이 필요한가 (연관 이슈 링크:
Fixes #123) - How: 어떻게 구현했는가 (접근 방식, 대안을 고려했는지)
- Test: 어떻게 테스트했는가 (테스트 추가 여부, 수동 테스트 방법)
CONTRIBUTING.md를 반드시 읽어라
대부분의 프로젝트에는 CONTRIBUTING.md 파일이 있다. PR 형식, 브랜치 전략, 테스트 실행 방법, CLA(Contributor License Agreement) 서명 여부 등이 명시되어 있다. 이를 무시하고 보낸 PR은 메인테이너가 가이드라인을 따르라며 닫아버리는 경우가 많다.
코드 리뷰 대응 — PR이 통과되는 방법
PR을 보낸 후 리뷰가 돌아오면 어떻게 대응하느냐가 PR 통과 여부를 결정한다.
리뷰 댓글 유형별 대응
- 명확한 수정 요청: 군말 없이 수정하고 재요청. 수정했다는 댓글로 알려라.
- 의견 차이 (Discussion): 자신의 접근 방식이 맞다고 생각하면 이유를 설명하라. 단, 방어적으로 되지 말고 "다음과 같이 생각했는데, 혹시 이 케이스를 고려하지 못한 것인가요?" 같은 톤으로.
- nit 댓글: "nit:" 또는 "optional:"으로 시작하는 댓글은 권고 사항이다. 수정하면 좋지만 메인테이너도 강요하지 않는다. 시간이 있으면 수정하는 것이 좋은 인상을 남긴다.
리뷰 후 커밋 관리
리뷰 피드백을 반영할 때 새 커밋을 추가하는 것이 일반적이다. PR 히스토리를 깨끗하게 유지하려면 머지 전에 squash하거나 rebase하는 경우가 있는데, 프로젝트 정책을 따라라. 일부 프로젝트는 "Please squash your commits"라고 요청한다.
응답이 없을 때
PR을 보낸 후 2주 이상 응답이 없다면 정중하게 ping 댓글을 달아도 된다. "Hi, any updates on this PR? Happy to make any changes if needed." 1달 이상 응답이 없다면 해당 프로젝트가 실질적으로 유지보수되고 있지 않을 수 있다.
첫 PR 이후 — 기여자에서 메인테이너로
첫 PR이 머지되면 그 다음은 반복이다. 기여가 쌓이면 자연스럽게 신뢰가 쌓이고, 메인테이너 권한을 받는 경로로 이어진다.
기여 범위 넓히기
- 이슈 트리아지: 새로 올라온 이슈를 재현하고 재현 여부나 추가 정보를 댓글로 남기는 것도 가치 있는 기여다.
- PR 리뷰 참여: 다른 사람의 PR에 코드 리뷰 의견을 남길 수 있다. 메인테이너 권한이 없어도 Suggestions를 달 수 있다.
- 문서 개선: API 문서 오탈자, 오래된 예시 코드 업데이트, 설치 가이드 보완 등은 쉽게 시작할 수 있으면서 실제로 많이 쓰이는 기여다.
- 테스트 추가: 커버리지가 낮은 부분을 찾아 테스트를 추가하는 것도 환영받는 기여다.
메인테이너가 되는 경로
오픈소스 프로젝트에서 메인테이너 권한을 받는 것은 일반적으로 초대 방식이다. 꾸준히 기여하고, PR 리뷰에 적극 참여하며, 커뮤니티에서 도움을 주다 보면 메인테이너로 초대받는다. 직접 "메인테이너로 만들어 달라"고 요청하는 것은 대부분 역효과다.