[오픈소스 컨트리뷰션 가이드] 12개월, PR 149개, 아파치 프로젝트 컨트리뷰터, Jackson 컨트리뷰터+멤버가 되면서...

Part 1. 용어 정리

• OSS
  • OpenSource Software, 오픈소스 소프트웨어의 약자
  • 본 글에서 오픈소스 프로젝트 같은 의미로 사용할 예정이다.
• Apache Pulsar
  • Kafka 와 같은 클라우드 네이티브 메시징 시스템 및 플랫폼
  • Yahoo에서 처음 시작되었고 이후 Apache 재단에 인큐베이팅, 그리고 메인으로 졸업
• Jackson
  • ObjectMapper 로 많이 알려져있는 프로젝트
  • ObjectMapper 는 Jackson 팀이 관리하는 jackson-databind 라는 프로젝트의 API
  • 정확한 명칭은 FasterXML 이라는 팀이 있고 이 팀의 멤버들이 jackson-databind, jackson-module-kotlin 등의 라이브러리들을 관리한다.

---

Part 2. 서론

최근 내가 메인으로 참여하는 FasterXML/jackson-databind 프로젝트에서 누적 PR이 100개를 넘었습니다.

PR 100개 병합이 지닌 의미의 크고 작음은 각자 판단에 따라 달라 빠르게 넘어가고 대신 오픈소스를 시작하는 분들에게 저의 노하우, 인사이트, 경험 등을 조심스레 공유해보고자 합니다.

---

Part 3. 개요

3-1. 글 목표

제가 오픈소스 활동을 통해 얻은 노하우, 인사이트, 경험들을 바탕으로 수월한 오픈소스 활동을 위한 가이드를 제공하고자 합니다.

3-2. 대상 독자

특정 오픈소스 프로젝트에 중/장기적으로 활동하고자 하는 분들에게 도움이 되고자 합니다.

PR 몇개 머지하는 것이 목표인 경우 본 글은 도움이 덜 될 것으로 생각됩니다.

3-3. 현재까지의 오픈소스 활동 내역

(제목을 풀어헤쳐보면) 2023년 1월부터 오픈소스 활동으로…..

• 12개월 동안
• PR 149 개를 머지하고
• Apache Pulsar 에서
  • “Apache Pulsar In Action” 책의 핵심 부분 번역 글 작성하고 (🔗링크 : https://vince-kim.tistory.com/category/Apache Pulsar)
  • 분석 일주일만에 첫 PR로 버그 픽스를 머지하고
  • Pulsar 팀의 공식 작업 제안서인 PIP(Pulsar Improvement Prosal)을 통과시키고 작업 진행하는 경험을 하고
  • 이후 20개 정도의 크고 작은 PR 병합하고
• Jackson 에서
  • 120+ 개의 PR 병합하고
  • 그 과정에서 팀 멤버가 되고
  • 팀의 연관 프로젝트 운영에 참여하고
• 그 모든 과정에서 자바 챔피언, 아파치 PMC 멤버, Yahoo 엔지니, Oracle 엔지니어, 구글 엔지니어 등과 협업하는

….. 소중한 경험들을 해왔습니다.

 

3-4. 목적 (시작 계기)

제가 오픈 소스를 시작한 계기를 짧게 설명하자면 “세계 수준의 엔지니어들과 협업하는 경험을 오픈소스 활동을 통해 쌓는다” 였습니다.

길게 설명하자면 최근 가입한 모임에서 내가 작성한 자기소개 내용…..

…..에서 두 개의 키워드, “소수정예”와 “기하급수적인 생산성”을 짚으며(point out) 시작됩니다.

“소수정예”와 “기하급수적인 생산성”은 현재 저의 삶의 지향점입니다.

이와 관련해서 저는 지속적으로 생각하고, 고민하고, 면접 볼때도 이야기하고, 타인에게 공유합니다.

그러다 어느 순간 스스로에게 이런 질문을 던졌습니다.

“내가 인스타그램, 왓츠앱과 같은 세계적인 엔지니어링 팀의 수준에 도달하기 위해 지금 내가 할 수 있는 것은 뭘까?”

답은 오픈소스 컨트리뷰션였습니다.

---

Part 4. 오픈소스 컨트리뷰션 가이드 (본문)

4-A. 회사보다 더 목적 중심입니다

 

본 글에서 오픈소스를 회사와 계속해서 비교하는 이유이기도 합니다.

오픈소스하는 사람들은 목표만 다를 뿐 직장, 회사보다 더 목적 중심입니다.

회사에서는 종종 사내 정치나 이해관계의 충돌이 있습니다.

오픈소스는 회사보다 프로젝트 성공에 대한 논의의 비중이 상대적으로 많이 큰 편입니다.

잘 생각해보면 당연한데, 오픈소스 활동은 대부분 비영리(non-profit)이기 때문입니다.

즉, 오픈소스에 참여하는 사람들은 자원봉사자들인 것이지요.

금전적인 이득이 없으니 이 사람들은 더더욱 본인들이 원하는 것(동기, motivation)에 더더욱 충실하게 됩니다.

이들의 동기(Motivation)는 명예, 관심사, 재미 등 다양하지만 궁극적으로 프로젝트가 가장 잘되게 하는 것 이라는 목표는 동일합니다.

 

4-B. PR 대신 프로젝트와 팀을 먼저 알아가기 (문서 읽기)

회사에서 신규입사자는 회사의 핵심가치, 분위기, 문화, 역할, 업무 프로세스 등을 먼저 파악하기 시작합니다.

OSS 에도 동일하게 적용됩니다.

진지하게 중/장기적인 참여를 목표하신다면 해당 프로젝트의…..

가치관, 사상, 설계, 팀의 소통 방법, 버그 제보 및 해소 프로세스, 기여 방식, 코딩 스타일, 구성원 성향, 테스트 코드 스타일, 계획된 마일스톤, 도움이 많이 필요한 부분

…..등을 찾아보고 이해하면 좋습니다.

그런 것들을 전부 어디서 찾아? 라고 물으신다면 깃허브에 전부 나와있습니다.

별도 웹사이트가 있을 수도 있고 깃허브 위키, README.md 등 사방에 적혀있습니다.

만약 특정 OSS 에 진득하게 참여한다면 PR 한 두개 올리는 것에 대해 조급해할 필요없으며 그보다는 진정으로 참여할 수 있도록 서로를 알아가는 시간을 가지는 것이 크게 도움됩니다.

입사하면 회사와 팀에 대해 먼저 알아가듯이 OSS 프로젝트와 팀에 대해 먼저 알아가는 것이 빠르게 중요한 역할을 맡게되는 길이라 생각됩니다.

 

4-C. 명확한 목적을 가지고 움직이기

OSS 개발시에는 리팩토링 하나도 명확한 문제/목표가 있어야 합니다.

우리는 종종 프로젝트를 갈아엎는다고 하는데 OSS 에서 그런 사고가 통할 가능성은 매우 희박하며 사소한 리팩토링도 별반 다르지 않습니다.

위에서 OSS 팀들은 매우 목적 중심이라고 언급했습니다.

해결할 문제거나 의도가 불분명한 작업들은 빠르게 잊혀집니다.

계속 푸시한다고해도 더 많은 설명과 논의들이 필요하게 되고 현실화되기 어려워집니다.

알고리즘, 클린코드(를 위한 리팩토링), 디자인 패턴, 아키텍처들은 결국 해결하고자하는 문제에 대한 수단입니다.

이 과정에서는 적절한 트레이드 오프를 고려하고 적용됩니다.

거의 대부분의 서비스 코드와 마찬가지로 오픈소스 프로젝트들의 코드들도 들여다보면 아름다움, 완벽과는 거리가 멉니다.

 

4-D. 중요도가 높을 수록 협업하기 쉽다

 

회사에서 제품 개발시 정해지는 작업의 우선 순위들은 오픈소스에도 그대로 적용됩니다.

OSS 팀이 더 중요하게 생각하는 것들을 할 수록 관심과 피드백을 더 많이 받게되어 작업하기가 쉬워진다는 이야기입니다.

아래 목록은 우리가 회사에서 작업의 중요도를 정하는 것과 유사하게, OSS 작업시 우선 순위와 관련된 설명을 포함합니다.

중요도도가 높은 것부터 시작하며 부연 설명도 달아두었습니다.

1. 문의 사항 대응
   1. 강력 추천, 프로젝트 이해도 향상 및 OSS 운영 방식을 알아갈 수 있는 매우 효과적인 방법입니다.
   2. 커뮤니티 플랫폼으로는 Github Discussions 페이지, 슬랙 채널, 메일링 리스트, StackOverflow(줄여서 SO) 등이 있습니다. 유저들이 사용법, 디자인 가이드, 버그 여부 등을 문의하면 찾아보고 답변해주면 이해도가 빠르게 올라갑니다.
   3. 우리가 답변하는 것과 무관하게 OSS 팀에서도 거의 대부분 답변을 해주기 때문에 그분들과도 소통을 하게됩니다.
2. 버그 수정
   1. 난이도는 케바케입니다.
   2. 대신 실패하는 테스트 케이스가 명확하니 상황에 따라 개발하기 수월합니다.
   3. 버그 수정은 릴리즈 일정에 큰 영향을 주기 때문에 다들 좋아합니다.
3. 기능 개발
   1. 아이디어를 모으고 의견을 주고 받아야 하며 컨텍스트를 파악해야해서 제일 어렵습니다.
   2. 이해도가 낮을 때는 논의만 하다 끝날 확률이 매우 높습니다.
   3. 대신 한번 하고나면 full 싸이클 한번 도는 셈이라 자신감도 생기고 활동에 관성처럼 탄력도 붙습니다.
   4. 제대로 된거 하나 하고나면 꽤나 익숙해졌다고 볼 수 있겠습니다.
   5. 빠른 피드백을 원한다면 깃허브 이슈 라벨 중 "most-wanted" , 또는 "important" 등을 시작하면 됩니다.
4. 개발환경 개선
   1. 디펜던시 정리, Github 자동화 등의 작업들도 많이들 환영하는 것들입니다.
5. 문서화
   1. 문서화를 귀찮아하는 것은 만인의 공통인 것 같습니다.
   2. 문서화 작업도 다들 환영하는 작업이며 진행시 덤으로 프로젝트에 대한 이해도도 증가합니다.
   3. 문서화 개선하다보면 본업에서 개발시에도 소스코드나 문서 읽는 것에 익숙해집니다.
6. 그리고 나머지 작업들....

 

4-E. 성공하는 PR 작성법

 

(경험상) 수월하게 진행되는 PR 의 공통점들을 종합한 것입니다.

1# 코딩 스타일

참여 초기일수록 코드 변경사항의 스타일은 기존 코드베이스와 유사하게 가져가는 것이 좋습니다.

우리 스스로가 생각하는 컨벤션과는 거리가 멀겠지만 세상은 정말 다양한 스타일 가이드들이 생기고 사라져왔기 때문에 나중에 보면 대부분 이유와 히스토리가 있는 것들인 것을 알게됩니다.

가볍게 팁을 드리자면 비슷하게 구현된 다른 클래스/컴포넌트를 참고해서 개발한 후, PR 에서 언급하면 PR의 정당성이 높아진다.

2# 변경사항 규모

PR이 클수록 진행 속도는 큰 폭으로 느려집니다.

거대한 PR은 애초에 좋지 않은 프랙티스일 뿐더러 다들 퇴근하고 짬내서 리뷰하는 케이스라 그런지 길게 작성한 PR을 부담스럽게 생각하는 편인 것으로 보입니다.

3# 테스트 코드

거의 대부분의 경우 테스트 코드를 같이 들고 가야합니다.

테스트 없이 내 수정본이 온전하고 앞으로도 온전할 것이라는 것을 어떻게 증명할까요?

만약 테스트 코드가 없어도 된다 믿는다면 그 (확실한) 이유를 PR 작성 시점부터 함께 전달하는 것을 추천드립니다.

만약 코드 수정은 했는데 어떻게 테스트 작성할 지 모를 경우, 수정한 클래스/파일로 검색해보면 비슷한 테스트들이 있을 것이다.

팁으로 버그 픽스 작업들은 대부분 Reproducible Case (반복해서 재현가능한 케이스)가 있기 때문에 테스트 작성에 수월합니다.

4# 전반적인 PR 프로세스

대상 OSS 프로젝트 스케일이 클수록 복잡한 부분입니다.

깃허브를 벗어나 JIRA 티켓 부터 시작하는 경우도 있습니다.

계기, 시작, 방법, 리뷰 등 다른 PR 들의 생명주기들을 계속 보다보면 익숙해집니다.

추가로 다른 PR에서 코드 상의 실수가 보이면 흔쾌히 리뷰 남겨주는 것 또한 팀과 친해지는 방법입니다.

 

4-F. 더 환영받는 Typo Fix (오타수정 PR) 는 어떤걸까?

 

종종 오픈소스 컨트리뷰션 시작으로 Typo Fix 를 추천하기도 합니다.

오픈소스 팀은 Typo Fix 작업도 임팩트있는 것을 좋아합니다.

다들 퇴근하고 깃허브에 접속하게되고 기능 개선이나 버그 수정 대신 Typo Fix PR 리뷰하다 하루가 다 지나갈 때의 기분이 어떨지 상상해보면 좋을 것 같습니다.

아래 실제 케이스 스터디를 통해 더/덜 환영받는 Typo Fix PR 를 살펴보겠습니다. (케이스들이 너무 극단적일까 싶어 걱정되지만….)

Typo Fix 가 예시이기는 하나 다른 작업들에도 유사하게 적용 가능하다고 생각합니다.

 

4-F-1. Case : 더 환영받는 Typo Fix

 

변경사항

topic-compaction-remain-null-key 라는 설정 값을 topic-compaction-retain-null-key 로 수정

 

설명

“Remain” 과 “Retain” 이라는 두 단어는 관점에 따라 매우 다른 의미를 가지게 됩니다.

“Remain”은 “남겨지는 것”이고 “Retain”은 “남기는 것”입니다.

기대 효과로는 프로젝트 운영관점에서 본 Typo Fix를 통해…..

1. 유저들이 해당 설정값 사용시 혼선을 예방
2. 혼선으로 인한 잠재적 버그, 유저들의 항의 감소

….. 해서 환영 받을 만한 PR 입니다.

실제로 저도 Apache Pulsar 의 소스코드를 분석하다가 발견한 PrecisPublishLimiter 를 PrecisePublishLimiter 로 수정하는 PR을 올린적도 있습니다.

눈에 거슬리고 좀 단어가 드러나지 않아 PR 을 올렸고 Apache Maintainer 한 분이 본인도 눈에 거슬렸는데 수정해줘서 고맙다는 이야기를 하신 적도 있습니다.

 

4-F-2 Case : 덜 환영받는 Typo Fix

 

변경사항

소스코드 주석의 “// sinc 2.17" 를 “// since 2.17”로 수정

[ BEFORE ]

// sinc 2.17
public void someMethod() {
        return true;
}

[ AFTER ]
// since 2.17
public void someMethod() {
        return false;
}

 

설명

주관적인 제 의견으로는 sinc 2.17 도 의미전달에 큰 문제가 없습니다.

그럼에도 불구하고 오타는 오타이기 때문에 "e" 를 추가해서 PR 을 올리면 언젠가 병합될 수도 있습ㅂ니다.

머지되는 것은 작업자 입장에서는 기뻐할만한 일이지만 이런 PR 들이 빈도가 잦아지면 환영 받지 못할 수도 있는데 이유는…..

1. 깃허브에서 버젓이 공간을 차지하며 버그 픽스와 같은 더 중요한 것들이 묻히게 됩니다.
2. 프로젝트 팀에 인지부하와 시간소모를 발생시킵니다 —보통 2개 이상의 메이저 버전을 동시에 관리하기 때문에 forward/backward-merge 도 해줘야해서 번거로워집니다.
3. 커밋 히스토리가 필요 이상으로 길어집니다.

특정 프로젝트에 지속적인 PR 을 올리고 싶다면 고민해볼 필요가 있습니다.

이직해서 새로운 회사에 입사했다고 상상해보자면.... 입사 후 첫 작업으로 Typo Fix PR 연속으로 올리는 게 팀에 도움이 될지를 잠시 고려해보면 좋을 것 같습니다.

 

4-F-3 : Case 2 를 더 환영받게 만드는 방법

 

설명

위에서 Case 2 “sinc” Typo 를 너무 부정적으로 이야기한 것으로 느낄 수도 있을 것 같습니다.

사실 중요도와 무관하게 오타는 오타입니다.

사람이라면 자연스랍게 오타가 눈에 거슬리기는 할 것이지요.

꼭 하고싶다면 효과적으로 하는 방법 찾아서 하면 좋을 것 같습니다.

예시로 저 였으면 했을 법한 방법을 소개드려봅니다.

읽어보시고 가능하면 더 효과적인 방법들도 스스로 생각해보시기를 희망합니다.

 

제안 : 좀 개선된 Typo Fix PR

비슷한 유형, 클래스 또는 패키지 단위로 Typo 들을 프로젝트 전반에 걸쳐서 수정하되 큰 규모는 자제하기

1. 유형의 종류나 위치를 최소화해서 리뷰어의 인지부하를 최소화한다
2. 이왕 하는거 관련된 것들의 일관성을 맞추면 서로 성취감도 생긴다.
3. 한줄 한줄 다 읽어보기 때문에 양이 너무 많으면 상당히 부담이 될 뿐만 아니라 틀린 부분이 나올 가능성도 높아져서 논의가 길어지고 결국 필요 이상으로 작업이 길어지게 된다.

 

4-G. 중꺽그마 (중요한 건 꺽여도 그냥 하는 마음)

 

이건 OSS 한정은 아니지만 그래도 말씀드리자면… 의지가 꺾여도 계속해서 시간을 투자해서 팀에 뭐라도 도움을 줄 것을 추천드립니다.

잘보이기 위해서가 아니라 우리 스스로 해당 프로젝트와 친해지는 길입니다.

가끔은 말투가 너무 공격적인 분들도 있는데요, 무시하시면 됩니다.

대부분 팩트 기반으로 이야기하기 때문에 사실 도움이 되는 경우가 많습니다.

피드백만 수용하시면 되고 사실 전 세계 사람들이 참여하다보니 영어가 모국어가 아닌 경우가 많아 표현이 서툰 경우도 있습니다.

그리고 하루의 일정 비중의 시간을 정해서 지속하는 것도 추천드립니다.

하는 만큼 잘하게 됩니다.

잘 되는 것도 그냥하고 안 되는 것도 그냥 하다보면 익숙해집니다.

 

4-H. 입문자를 환영하는 "good first issue"

 

컨트리뷰션 시작 시에 할만한 작업을 찾아보고자 (위 사진) Github 이슈 페이지에서 good-first-issue 라벨이 달려있는 이슈들을 찾아보기도 합니다.

good first issue 이슈들 찾아볼 때 고려해볼만한 것들은....

 

1. 난이도는 케바케

: 사실 maintainer 의 주관에 난이도가 낮아보이는 것들이라서 실제 난이도가 항상 beginner-friendly 하지는 않다는 점

 

2. 나에게 good first issue 는 모두의 good first issue

: 오픈소스 생태계는 글로벌하기 때문에 모두가 good first issue 로 시작하려고 한다는 점도 감안하면 프로젝트의 인지도가 높을 수록 공급이 수요를 따라가기 어렵다는 점도 감안해야합니다.

: good first issue 는 조금만 난이도가 올라가면 조금만 건들여보다가 빠지는 사람들이 대다수라서 maintainer 들도 피로도가 좀 있을 수도 있습니다. 그래서 어쩌면 위에서 언급한 것처럼 최대한 단순한 bug fix 를 해보는 것도 방법일 것으로 생각됩니다.

 

---

Part 5. 서둘러 마치며….

글이 길어지는 것 같아 빠르게 끊어봅니다.

추가적인 내용은 요청해주시면 시간되는대로 pt.2 로 작성해보겠습니다.

말투가 Part.1 부터 3까지 다소 딱딱하게 느껴졌다면 미리 사과드립니다 ㅜㅜ —글이 길어져서 의도적으로 지금처럼 썻습니다.

언제나 그렇듯이… 읽어주셔서 감사하며 많은 피드백 부탁드립니다!

김주혁 올림

PS : 티스토리 알림을 못 받아서 질문은 제 링크드인으로 메시지 주시면 빠른 답변 드리도록 하겠습니다!

https://www.linkedin.com/in/joo-hyuk-kim/