첫 오픈소스 컨트리뷰션, A부터 Z까지 살펴보기 (feat. Github Docs)

개발할 때 손쉽게 활용할 수 있는 고마운 오픈소스, 누가 만들었을까요? 수많은 오픈소스 contributor들이 기여한 코드 한 줄 한 줄이 모여 만들어진 오픈소스는 현재까지도 활발하게 기능이 추가되거나 수정되고 있습니다. 오픈소스 컨트리뷰션에 관심은 있었지만 어렵게 느껴졌다면, 이 글을 읽고 자신에게 가장 쉬운 방법으로 오픈소스에 기여해보세요.

오픈 소스 컨트리뷰션 유형

오픈 소스 컨트리뷰션이 어렵다고 느끼는 이유는 아마도 ‘오픈 소스 컨트리뷰션 = 소스 코드 작성’이라고 생각하기 때문일 겁니다. 실제로 오픈소스 컨트리뷰션의 유형은 매우 다양합니다.

• 오타 수정
• 번역
• 디자인 작업
• 의견 제시
• 가이드 문서 작성 및 개선
• 소스 코드 작성 및 개선

이외에도, 프로젝트에 도움이 되는 것은 사소한 것이라도 컨트리뷰션 대상이 될 수 있습니다.

이 중에서도 저는 “가이드 문서 작성 및 개선”을 통해 Github Docs에 컨트리뷰션했던 경험을 소개하고자 합니다.

Github Docs 컨트리뷰션 과정

Step 1. 이슈 발견

Github actions를 사용해서 Redis 컨테이너를 띄우기 위해, github Docs에서 관련된 Creating Redis service containers 문서를 찾았습니다. 그런데 문서에서 제공하는 예시 코드를 그대로 옮겨 실행해 보는 과정에서 에러가 발생했습니다.

TypeError: redisClient.hset is not a function

에러는 redis 모듈로 생성한 redis client 객체 내부에 hset() 함수가 없다는 내용이었습니다.

아래는 에러가 발생한 Client.js 코드 중에서 일부를 발췌한 코드입니다.

모듈 node-redis의 공식 문서를 읽어보니, GitHub Docs Client.js에서는 볼 수 없었던 두 가지 큰 차이점을 발견했습니다.

1. connect() 함수를 사용해서 redis client가 서버와의 connection을 만드는 부분이 추가되었다.
2. hset() 대신 카멜 케이스를 적용한 hSet()를 사용한다.

이를 통해 Client.js 작성 시점에서 설치되었던 node-redis 버전과, 최신 버전인 node-redis v4와의 버전 차이로 인해 에러가 발생했음을 예상할 수 있었습니다. 예상대로 node-redis의 v3 to v4 Migration Guide에 해당 변경 사항이 명시되어 있었습니다.

함수 명에 카멜 케이스가 적용된 부분은 migration Guide에는 적혀 있지 않았지만, node-redis 공식 문서 메인 페이지에서 찾아볼 수 있었습니다.

이 외에도, 에러를 핸들링하는 방식이나 redis client를 생성하는 함수의 input 구조도 달라졌다는 것을 알 수 있었습니다.

결국 Redis v4와 v3를 비교해 본 결과, 구문과 내부 동작이 완전히 다르기 때문에 github/docs repository에 해당 이슈를 공유하고 에러를 해결하고자 했습니다.

Step 2. 컨트리뷰션 가이드 확인

대부분의 오픈소스는 컨트리뷰션 가이드를 제공하는 경우가 많습니다. github/docs에서도 Contributing Guide를 제공하고 있습니다. 처음에는 가이드를 제공하는지 몰라서 늘 하던대로 ✨눈치 스킬 ✨을 꺼냈습니다. 다른 사람들이 github/docs에 어떻게 PR을 생성했는지 눈치껏 살펴보니, 일반적으로 Issue를 생성한 후 PR에 Issue를 연결해서 작성한다는 것을 알게 되었습니다. Issue 생성 템플릿을 확인하고 나서야, Contributing Guide를 제공한다는 것을 알 수 있었습니다.

Contributing Guide에서는 아래와 같은 내용을 확인할 수 있습니다.

• Discussions: 이슈에 대한 논의가 필요하다면, Discussions를 이용해라.
• Issue: Issue를 작성하기 전에, 같은 내용의 Issue가 존재하는지 체크해라. 유일하다면 템플릿을 사용해서 작성해라.
• Pull requests: PR을 작성하기 전에, 가이드에 적혀있는 체크리스트를 기반으로 self-review를 진행해야 한다.

가이드에 안내된 대로 같은 내용의 Issue가 없는지 체크하고 나서, 컨트리뷰션을 진행하였습니다.

Step 3. Issue 작성

이슈를 작성할 때 가장 신경 써야 하는 부분 중 하나는 제목입니다. Issue가 어떤 내용을 담고있는지 쉽게 유추할 수 있도록 제목을 지어야 합니다. 저는 github/docs 내의 특정 코드에서 redis 모듈을 사용하는 방식에 버전 이슈가 있다는 것을 드러내고 싶었습니다.

그다음으로는 Issue 내용을 살펴보겠습니다.

Issue 템플릿은 4가지 섹션으로 나누어져 있습니다.

• Code of Conduct
  Issue를 생성하기 전에 점검해야 할 체크리스트입니다.
• What article on docs.github.com is affected?
  수정하고자 하는 문서 링크와 함께, 에러 발생의 근본적인 원인이 되는 코드 위치도 첨부했습니다.
• What part(s) of the article would you like to see updated?
  문서의 어느 부분에서 어떤 문제가 발생했는지 상세하게 작성했습니다.
• Additional Information
  에러 상황을 캡처한 이미지를 첨부해서 Issue에 대한 이해를 돕고자 했습니다.
  (+ 영어로 적는 것을 두려워하지 마세요. 저희에겐 Google 번역기와 파파고가 있습니다!)

Issue를 올린 다음 날, collaborator께서 확인하고 코멘트를 달아주셨습니다. Issue를 올린 당일에 PR도 함께 올렸는데, PR 올릴 때 해당 Issue를 mention 함으로써 Issue와 PR 간의 연결성이 생기고 tracking이 간편해졌습니다.

Step 4. 작업 수행

If you want to create a new branch for your pull request and do not have write permissions to the repository, you can fork the repository first.

PR을 요청하는 데에는 여러 가지 방법이 있지만, 저는 그중에서도 repository를 fork 해서 작업하는 방식으로 진행했습니다. github docs에서 관련 가이드를 제공하고 있는데, 작업 당시에는 알지 못했습니다. 이럴 때 제 ✨눈치 스킬 ✨이 또 한 번 요긴하게 쓰입니다. github/docs repository에서 new branch 버튼이 invisible 처리되어 있는것을 확인하고 나서, fork를 통해 PR을 생성하는 방식을 선택하였습니다.

repository를 fork 했으면, 작업 브랜치를 생성해야 합니다. 우선, 브랜치 네이밍에 관련한 내용이 contributing 가이드에 있는지 확인합니다. 가이드에서 찾을 수 없다면? 다시 한번 ✨눈치 스킬 ✨을 꺼낼 때가 된 것 같습니다. 다른 contributor가 작성한 PR들 중에서 성공적으로 merge 후 closed 된 것들을 관찰해 보세요. github/docs에서는 대부분 patch-{number}형식으로 브랜치명을 지정하는 것을 볼 수 있었습니다.

저는 작업 성격 및 순서에 따라 commit을 3가지로 나누었습니다.

1. legacy mode를 사용해서 v3 문법 유지하면서 코드를 수정했습니다.
2. 코드와 일치하지 않는 주석을 수정했습니다.
3. legacy mode를 사용하지 않고, v4 문법에 맞게 코드를 수정했습니다. 이 과정에서, ES6 문법에 맞게 비동기 처리를 수행하도록 하였습니다.

제가 작업한 결과를 한눈에 볼 수 있는 Changes for all commits입니다.

이렇게 생성한 브랜치에 작업물을 commit하고 push까지 진행하여 PR 작성을 위한 준비를 마쳤습니다.

Step 5. PR 작성

PR을 작성할 때도 마찬가지로 제목을 잘 짓는 것이 중요합니다. 해당 PR이 어떤 부분에 기여하고자 하는지가 제목에 잘 드러나도록 작성해야 합니다. 저는 github/docs에서 제공하는 파일인 creating-redis-service-containers.md를 개선하고자 하는 PR 임을 드러내는데 집중했습니다.

그다음으로는 PR 내용을 살펴보겠습니다.

PR 템플릿은 3가지 섹션으로 나누어져있습니다.

• Why
  해결하고자 한 Issue 번호를 링크했습니다.
• What’s being changed
  (if available, include any code snippets, screenshots, or gifs)
  어떻게 작업을 진행하고 commit했는지 단계별로 간략하게 설명했습니다. 그리고 제가 작업한 코드를 기반으로 직접 action-runner를 실행한 결과를 첨부하여, 이 PR이 해당 Issue 해결에 도움이 된다는 것을 간접적으로 보여주고자 했습니다.
• Check off the following
  PR을 올리기 전에 점검해야 할 체크리스트입니다. 위에서 언급한 self-review checklist가 첨부되어 있습니다.

PR을 올린 다음 날 collaborator께서 확인하고 코멘트를 달아주시면서 PR 성격에 맞는 태그도 붙여주신 것을 볼 수 있었습니다.

reviewer가 백로그에 쌓여있는 PR들을 확인할 때, PR에 붙어있는 태그들을 보면 어떤 PR 인지 유추하는 데에 도움이 될 것입니다.

이렇게 PR을 작성했으면, 컨트리뷰션 제출 단계까지 마무리되었습니다.

Step 6. PR merge 까지 경과 지켜보기

컨트리뷰션이 실제로 이루어지기 위해서는, PR이 merge 되어야 합니다. 그러기 위해서는 reviewer에게 리뷰를 받는 과정이 필요합니다. 리뷰 과정에서 reviewer로부터 코드 수정 요청을 받을 수도 있고, PR 제출이 거절될 수도 있습니다. 심지어는 리뷰조차 받지 못하는 경우도 발생합니다. 실제로 제가 제출했던 PR은 제출한지 무려 10개월 만에 merge 되었습니다.

오랜 기간 동안 쌓인 PR conversation 히스토리를 보다보면 흥미로운 활동들이 눈길을 끕니다 . github action-bot에 의해 SME Stale 태그가 계속해서 붙고, collaborator는 SME Stale 태그를 계속해서 제거하는 과정이 반복됐었다는 것을 알 수 있습니다. 또한 스팸성 코멘트가 달리기도 합니다. 저는 그중에서도 ‘approve’라고 달렸던 코멘트가 매우 인상 깊었습니다. 궁금하신 분은 여기서 직접 확인해 보실 수 있습니다.

Extra Step. reviewer에게 질문하기

컨트리뷰션이 이루어지고 난 이후, reviewer에게 질문하고 싶은 2가지를 코멘트로 남겼습니다.

1. 긴 시간 동안 PR이 이루어지지 않았던 이유는 무엇인가요?
   단순히 리뷰할 시간이 부족해서인 건지, 아니면 내 PR에 부족함(예: 가독성, 영어 스킬)이 있어서인지 궁금했습니다. 부족한 점이 있다면 이 글을 읽는 독자와 공유하고 싶었고, 앞으로 더 나은 컨트리뷰션을 위해 고치고 싶었습니다.
2. 제 PR은 왜 아무런 피드백 없이 한 번에 merge 될 수 있었나요?
   아무래도 첫 컨트리뷰션인 만큼 수정해야 할 부분이 있을 거라고 예상했기 때문에 궁금했습니다.

기쁘게도 reviewer로부터 하루 만에 답변을 받을 수 있었습니다. 리뷰를 받은 지 두 달 가까이 지났는데도 불구하고, 상세하게 답변을 해주셨습니다.

1. 긴 시간 동안 PR이 이루어지지 않았던 이유는 단순한 인력 부족이었습니다.
2. PR이 한 번에 merge 된 이유는 제가 Issue와 PR을 통해서 좋은 정보를 제공했기 때문이라고 하셨습니다. 코드를 수정한 이유, 제가 올린 Issue 내용, 그리고 제 코드로 직접 github-actions를 실행해 증명해 낸 것 모두 충분했다고 말씀해 주셨습니다.

여기서 잠깐! reviewer, collaborator, 또는 다른 contributor와 소통할 때 주의해야 할 점이 있습니다. 바로, 궁금한 것이 있다고 해서 “개인적으로 연락하지 않는 것”입니다. 공개적인 의사소통은 오픈소스 프로젝트에서 필수적이라는 것을 기억해 주세요.

정리하며

Key Point

• repository에서 Contribution Guide를 제공하는지 확인하자. 만약 없다면, ✨눈치 스킬✨을 사용해서 다른 contributor가 남긴 contribution 흔적을 분석해라.
• PR을 생성할 때, 컨트리뷰션을 이해하는데 도움이 되는 정보를 충분히 제공해라.
• 오픈소스를 사용하다가 이슈를 발견했다면 주저 말고 기여해라! (feat. 든든한 Google 번역기와 파파고)

이 글이 여러분들에게 컨트리뷰션에 도전하는 계기가 되길 바랍니다. 오픈소스 컨트리뷰션에 대해 더 많은 정보를 알고 싶다면, 오픈소스 기여 방법이 잘 정리되어 있는 오픈 소스 가이드를 읽어보는 것을 추천합니다.

오픈소스에 기여하는 방법

README