Jotai 오픈소스 기여 완벽 가이드

Jotai 오픈소스 프로젝트에 처음 기여하는 개발자를 위한 완벽 가이드입니다. 기여 가이드 읽기부터 PR 작성, 코드 리뷰 대응까지 실무에서 바로 활용할 수 있는 모든 과정을 다룹니다.

---

목차

1. 기여_가이드_읽기
2. 이슈_찾기와_분석
3. 개발_환경_설정
4. PR_작성_방법
5. 코드_리뷰_대응
6. 오픈소스_에티켓

---

1. 기여 가이드 읽기

2-3문장으로 상황 설정 최근 Jotai를 사용하며 편리함을 느낀 김개발 씨는 문득 이런 생각을 했습니다. "나도 이 멋진 라이브러리에 기여할 수 있을까?" 선배 개발자 박시니어 씨에게 물어보니 "일단 기여 가이드부터 읽어보세요"라는 답변이 돌아왔습니다.

핵심 개념을 3-4문장으로 기여 가이드는 오픈소스 프로젝트에 참여하기 위한 첫 번째 관문입니다. 마치 새로운 회사에 입사할 때 업무 매뉴얼을 읽는 것과 같습니다.

Jotai의 기여 가이드에는 코딩 스타일, 커밋 메시지 규칙, 테스트 방법 등 프로젝트에 기여하기 위해 꼭 알아야 할 정보가 담겨 있습니다.

다음 코드를 살펴봅시다.

# Jotai 저장소 클론하기
git clone https://github.com/pmndrs/jotai.git
cd jotai

# CONTRIBUTING.md 파일 확인
cat CONTRIBUTING.md

# 주요 확인 사항들
# 1. 코드 스타일 가이드
# 2. 커밋 메시지 컨벤션
# 3. PR 템플릿
# 4. 이슈 라벨 체계

이북처럼 술술 읽히는 설명 김개발 씨는 Jotai 저장소를 열어 README 파일을 훑어봤습니다. 문서를 읽다가 CONTRIBUTING.md라는 파일을 발견했습니다.

"이게 바로 기여 가이드구나!" 박시니어 씨가 옆에서 설명을 덧붙입니다. "오픈소스 프로젝트마다 고유한 규칙이 있어요.

그걸 무시하고 PR을 보내면 십중팔구 거절당하죠." 기여 가이드란 무엇일까요? 쉽게 비유하자면, 기여 가이드는 마치 요리 레시피와 같습니다. 맛있는 요리를 만들려면 레시피에 적힌 재료와 순서를 따라야 하듯이, 좋은 PR을 만들려면 기여 가이드의 규칙을 따라야 합니다.

이 문서에는 프로젝트 메인테이너들이 원하는 코드 스타일, 커밋 방식, 테스트 방법 등이 상세히 기록되어 있습니다. 왜 기여 가이드를 읽어야 할까요? 기여 가이드를 읽지 않던 시절의 김개발 씨를 떠올려 봅시다.

그는 열정만 가득한 채 PR을 작성했지만, 메인테이너로부터 "커밋 메시지가 규칙에 맞지 않습니다"라는 피드백을 받았습니다. 다시 수정하고, 또 수정하기를 반복했습니다.

시간도 많이 걸렸고, 무엇보다 자신감이 떨어졌습니다. 더 큰 문제는 코드 스타일이 프로젝트의 기존 코드와 달라서 전체적인 일관성이 깨졌다는 점이었습니다.

프로젝트가 커질수록 이런 일관성은 정말 중요합니다. 기여 가이드는 어떻게 읽어야 할까요? Jotai 저장소의 루트 디렉토리에는 CONTRIBUTING.md 파일이 있습니다.

이 파일을 열면 크게 네 가지 섹션을 볼 수 있습니다. 첫 번째는 개발 환경 설정입니다.

Node.js 버전, 패키지 매니저 종류, 필요한 의존성 등이 명시되어 있습니다. Jotai는 pnpm을 사용하므로 npm이 아닌 pnpm으로 패키지를 설치해야 합니다.

두 번째는 코드 스타일 가이드입니다. ESLint와 Prettier 설정이 이미 프로젝트에 포함되어 있으므로, 코드를 작성한 후 pnpm lint를 실행하면 자동으로 스타일이 검사됩니다.

세 번째는 커밋 메시지 컨벤션입니다. Jotai는 Conventional Commits 형식을 따릅니다.

feat:, fix:, docs: 같은 접두사를 사용해야 합니다. 네 번째는 테스트 작성 방법입니다.

모든 새로운 기능이나 버그 수정에는 테스트가 필수입니다. pnpm test로 테스트를 실행할 수 있습니다.

실무에서는 어떻게 활용할까요? 실제로 많은 성공적인 오픈소스 기여자들은 기여 가이드를 체크리스트처럼 활용합니다. PR을 보내기 전에 "커밋 메시지 형식이 맞나?", "테스트를 작성했나?", "린트 검사를 통과했나?" 같은 항목들을 하나씩 체크합니다.

김개발 씨도 이 방법을 따라 했고, 첫 PR이 한 번에 머지되는 기쁨을 경험했습니다. 메인테이너는 "완벽한 PR이네요!"라는 칭찬까지 덧붙였습니다.

주의할 점도 있습니다 초보 기여자들이 흔히 하는 실수는 기여 가이드를 한 번만 대충 읽고 넘어가는 것입니다. 기여 가이드는 프로젝트가 업데이트되면서 함께 변경될 수 있으므로, PR을 보내기 전에 항상 최신 버전을 확인해야 합니다.

또한 기여 가이드에 없는 내용이라도 기존 코드의 패턴을 따라야 합니다. "가이드에 안 써있었어요"라는 변명은 통하지 않습니다.

정리하며 박시니어 씨가 마무리 조언을 건넵니다. "기여 가이드는 귀찮은 규칙이 아니라, 여러분을 돕기 위한 친절한 안내서예요." 기여 가이드를 꼼꼼히 읽는 것만으로도 여러분은 이미 절반의 성공을 거둔 셈입니다.

다음 단계로 넘어가 봅시다.

실전 팁

💡 실전 팁

• CONTRIBUTING.md를 북마크해두고 PR 작성 전마다 확인하세요
• 가이드에 나온 명령어들을 직접 실행해보며 익숙해지세요

---

2. 이슈 찾기와 분석

2-3문장으로 상황 설정 기여 가이드를 모두 읽은 김개발 씨는 이제 무엇을 고칠지 고민하기 시작했습니다. "어떤 이슈를 선택해야 할까?" 막막했던 김개발 씨에게 박시니어 씨가 GitHub 이슈 탭을 열어 보여줍니다.

핵심 개념을 3-4문장으로 이슈 선택은 오픈소스 기여의 두 번째 단계입니다. 마치 도서관에서 자신의 수준에 맞는 책을 고르는 것과 같습니다.

Jotai 프로젝트에는 'good first issue', 'help wanted' 같은 라벨이 붙은 초보자 친화적인 이슈들이 있으며, 이를 통해 무리 없이 첫 기여를 시작할 수 있습니다.

다음 코드를 살펴봅시다.

// GitHub에서 초보자용 이슈 찾기
// 1. Issues 탭 클릭
// 2. Labels 필터에서 'good first issue' 선택
// 3. 이슈 내용 분석

// 이슈 분석 체크리스트
const issueAnalysis = {
  // 이슈가 해결되지 않았는지 확인
  isOpen: true,
  // 다른 사람이 작업 중인지 확인
  isAssigned: false,
  // 내 실력으로 해결 가능한지 판단
  difficulty: 'beginner',
  // 이슈에 충분한 설명이 있는지
  hasDescription: true
};

이북처럼 술술 읽히는 설명 김개발 씨는 Jotai 저장소의 Issues 탭을 클릭했습니다. 무려 수백 개의 이슈가 나열되어 있었습니다.

"이 많은 이슈 중에서 뭘 골라야 하지?" 박시니어 씨가 화면을 가리키며 설명합니다. "왼쪽 Labels 필터를 보세요.

'good first issue'라는 라벨이 있죠? 초보자를 위해 메인테이너가 골라놓은 이슈예요." 이슈 찾기란 무엇일까요? 이슈 찾기는 마치 자신에게 맞는 운동을 선택하는 것과 같습니다.

처음 헬스장에 가면 가벼운 무게부터 시작하듯이, 오픈소스도 처음에는 간단한 이슈부터 도전해야 합니다. 무리하게 어려운 이슈를 선택하면 중도에 포기하기 쉽습니다.

Jotai 같은 성숙한 오픈소스 프로젝트는 초보자를 위한 이슈를 따로 라벨링해 둡니다. 'good first issue'는 "여기서부터 시작하세요"라는 친절한 안내판과 같습니다.

왜 이슈 선택이 중요할까요? 과거의 김개발 씨는 욕심이 앞섰습니다. 복잡한 성능 최적화 이슈를 선택했다가 일주일 내내 헤매다가 결국 포기했습니다.

자신감도 떨어지고, 오픈소스에 대한 흥미마저 잃을 뻔했습니다. 반면 적절한 난이도의 이슈를 선택했을 때는 달랐습니다.

하루 만에 해결하고 PR을 보낼 수 있었고, 머지되는 순간의 성취감은 이루 말할 수 없었습니다. 그 경험이 밑거름이 되어 점점 더 어려운 이슈에 도전할 수 있게 되었습니다.

어떤 이슈를 선택해야 할까요? 첫 번째 기준은 라벨입니다. 'good first issue', 'help wanted', 'documentation' 같은 라벨이 붙은 이슈를 찾으세요.

특히 문서 관련 이슈는 코드를 많이 작성하지 않아도 되므로 진입 장벽이 낮습니다. 두 번째 기준은 이슈의 명확성입니다.

이슈 설명이 구체적이고, 재현 방법이나 예상 결과가 명시되어 있는지 확인하세요. 모호한 이슈는 경험이 쌓인 후에 도전하는 것이 좋습니다.

세 번째 기준은 할당 여부입니다. 이미 누군가 작업 중인 이슈는 피하세요.

Assignees 항목이 비어있는지 확인하고, 댓글을 읽어보며 다른 사람이 작업 중인지 체크합니다. 이슈를 분석하는 방법 이슈를 하나 선택했다면 이제 본격적으로 분석할 차례입니다.

김개발 씨는 "atom의 onMount 옵션 타입 개선" 이슈를 발견했습니다. 이슈 본문을 읽어보니 현재 타입 정의가 너무 넓어서 실수를 유발할 수 있다는 내용이었습니다.

메인테이너가 "TypeScript 타입을 더 엄격하게 만들어주세요"라고 친절하게 방향까지 제시해 뒀습니다. 김개발 씨는 관련 코드를 찾아 읽어봤습니다.

src/core/atom.ts 파일의 50번째 줄 근처였습니다. 타입 정의를 살펴보니 어떻게 개선해야 할지 감이 잡혔습니다.

실무 활용 팁 성공적인 기여자들은 이슈를 선택한 후 바로 코딩하지 않습니다. 먼저 이슈에 "제가 이 이슈를 작업해도 될까요?"라고 댓글을 남깁니다.

메인테이너의 승인을 받으면 안심하고 작업할 수 있습니다. 또한 비슷한 이슈나 PR이 과거에 있었는지 검색해 봅니다.

이미 해결됐거나, 다른 방향으로 논의가 진행 중일 수도 있기 때문입니다. 주의사항 초보자들이 자주 하는 실수는 너무 오래된 이슈를 선택하는 것입니다.

6개월 이상 된 이슈는 이미 해결됐거나 우선순위가 낮을 가능성이 높습니다. 최근 3개월 이내에 활동이 있는 이슈를 선택하세요.

정리하며 박시니어 씨가 고개를 끄덕입니다. "좋은 이슈를 찾았네요.

이제 개발 환경을 설정해 볼까요?" 적절한 이슈를 선택하는 것만으로도 절반은 성공한 겁니다. 자, 이제 본격적으로 코드를 만질 시간입니다.

실전 팁

💡 실전 팁

• 첫 기여는 documentation이나 타입 개선 같은 간단한 이슈로 시작하세요
• 이슈에 댓글로 작업 의사를 밝혀 중복 작업을 방지하세요

---

3. 개발 환경 설정

2-3문장으로 상황 설정 이슈를 선택한 김개발 씨는 이제 코드를 수정할 준비를 합니다. "저장소를 포크하고, 클론하고, 의존성을 설치하고..." 박시니어 씨가 단계별로 알려주기 시작합니다.

핵심 개념을 3-4문장으로 개발 환경 설정은 실제 코드 작업을 시작하기 전 필수 단계입니다. 마치 요리를 하기 전에 재료와 도구를 준비하는 것과 같습니다.

Jotai는 pnpm을 사용하며, TypeScript로 작성되어 있어 Node.js와 올바른 패키지 매니저 설치가 필수입니다.

다음 코드를 살펴봅시다.

# 1. Jotai 저장소 포크하기 (GitHub 웹에서 Fork 버튼 클릭)

# 2. 포크한 저장소 클론
git clone https://github.com/YOUR_USERNAME/jotai.git
cd jotai

# 3. upstream 리모트 추가 (원본 저장소 연결)
git remote add upstream https://github.com/pmndrs/jotai.git

# 4. pnpm 설치 (아직 없다면)
npm install -g pnpm

# 5. 의존성 설치
pnpm install

# 6. 빌드 테스트
pnpm build

# 7. 테스트 실행하여 모든 것이 정상인지 확인
pnpm test

이북처럼 술술 읽히는 설명 김개발 씨는 Jotai 저장소 페이지 우측 상단의 Fork 버튼을 클릭했습니다. 잠시 후 자신의 계정에 Jotai 저장소가 복사되었습니다.

"이게 포크구나!" 박시니어 씨가 설명을 이어갑니다. "포크는 원본 저장소의 복사본을 만드는 거예요.

원본에 직접 수정할 권한은 없으니까요." 개발 환경 설정이란? 개발 환경 설정은 마치 새로운 집으로 이사 가서 가구를 배치하는 것과 같습니다. 코드 작업을 시작하기 전에 필요한 모든 도구와 설정을 갖춰야 합니다.

여기에는 저장소 포크, 클론, 의존성 설치, 빌드 확인 등이 포함됩니다. Jotai는 모노레포 구조로 되어 있고, pnpm 워크스페이스를 사용합니다.

따라서 npm이 아닌 pnpm으로 패키지를 관리해야 합니다. 왜 올바른 환경 설정이 중요할까요? 과거 김개발 씨는 이 단계를 대충 넘어갔다가 큰 낭패를 봤습니다.

npm으로 의존성을 설치했더니 버전 충돌이 발생했고, 테스트가 실패했습니다. 원인을 찾느라 반나절을 허비했습니다.

올바른 환경 설정은 시간 낭비를 막아줍니다. 프로젝트가 요구하는 정확한 버전과 도구를 사용하면, 로컬에서 작동하던 코드가 CI에서 실패하는 일을 막을 수 있습니다.

단계별 설정 과정 첫 번째 단계는 포크입니다. GitHub에서 Jotai 저장소를 열고 우측 상단의 Fork 버튼을 클릭하면, 자신의 계정에 저장소 복사본이 생성됩니다.

이제 이 복사본에서 마음껏 수정 작업을 할 수 있습니다. 두 번째 단계는 클론입니다.

포크한 저장소를 로컬 컴퓨터로 가져옵니다. git clone 명령어에 자신의 포크 URL을 입력하면 됩니다.

세 번째 단계는 upstream 설정입니다. 원본 저장소를 upstream이라는 이름으로 추가해 둡니다.

나중에 원본 저장소의 최신 변경사항을 가져올 때 필요합니다. 네 번째 단계는 pnpm 설치입니다.

Jotai는 pnpm을 사용하므로, 시스템에 pnpm이 없다면 npm install -g pnpm으로 설치합니다. 다섯 번째 단계는 의존성 설치입니다.

pnpm install을 실행하면 프로젝트에 필요한 모든 패키지가 설치됩니다. 이 과정은 몇 분 정도 걸릴 수 있습니다.

여섯 번째 단계는 빌드 테스트입니다. pnpm build를 실행하여 프로젝트가 정상적으로 빌드되는지 확인합니다.

에러가 발생하면 의존성 설치 과정에 문제가 있었을 가능성이 높습니다. 마지막 단계는 테스트 실행입니다.

pnpm test를 실행하면 모든 단위 테스트가 돌아갑니다. 모두 통과해야 정상입니다.

브랜치 전략 환경 설정이 끝났다면 작업용 브랜치를 만들어야 합니다. main 브랜치에서 직접 작업하면 안 됩니다.

김개발 씨는 git checkout -b fix/onmount-type이라는 명령어로 새 브랜치를 만들었습니다. 브랜치 이름은 작업 내용을 명확히 나타내야 합니다.

'fix/', 'feat/', 'docs/' 같은 접두사를 사용하면 의도가 명확해집니다. 실무에서의 환경 관리 많은 개발자들은 프로젝트마다 Node.js 버전이 달라서 곤란을 겪습니다.

이럴 때는 nvm(Node Version Manager)을 사용하면 편리합니다. Jotai의 .nvmrc 파일을 보면 권장 Node.js 버전이 명시되어 있습니다.

nvm use 명령어 하나로 프로젝트에 맞는 Node.js 버전으로 전환할 수 있습니다. 이렇게 하면 "로컬에서는 되는데 CI에서는 안 돼요" 같은 문제를 예방할 수 있습니다.

주의사항 초보자들이 자주 하는 실수는 upstream을 설정하지 않는 것입니다. 작업하는 동안 원본 저장소가 업데이트될 수 있습니다.

upstream을 설정해두지 않으면 나중에 충돌이 발생할 때 해결하기 어렵습니다. 또 다른 실수는 main 브랜치에서 직접 작업하는 것입니다.

반드시 별도의 브랜치를 만들어 작업하세요. 정리하며 박시니어 씨가 김개발 씨의 화면을 확인합니다.

"좋아요, 모든 테스트가 통과했네요. 이제 본격적으로 코드를 수정할 준비가 됐어요." 김개발 씨는 자신감이 생겼습니다.

제대로 된 환경 설정 덕분에 앞으로의 작업이 순조롭게 진행될 것 같습니다.

실전 팁

💡 실전 팁

• nvm을 사용하여 프로젝트별 Node.js 버전을 관리하세요
• 작업 시작 전 git fetch upstream && git rebase upstream/main으로 최신 코드를 동기화하세요

---

4. PR 작성 방법

2-3문장으로 상황 설정 코드 수정을 마친 김개발 씨는 이제 Pull Request를 작성할 차례입니다. "커밋은 어떻게 쓰지?

PR 제목은?" 처음이라 막막했던 김개발 씨에게 박시니어 씨가 PR 작성의 기술을 알려줍니다.

핵심 개념을 3-4문장으로 Pull Request 작성은 자신의 코드 변경사항을 원본 프로젝트에 병합해달라고 요청하는 과정입니다. 마치 편집자에게 원고를 제출하는 것과 같습니다.

좋은 PR은 명확한 제목, 상세한 설명, 깔끔한 커밋 히스토리를 갖추고 있어야 합니다.

다음 코드를 살펴봅시다.

# 1. 변경사항 스테이징
git add src/core/atom.ts

# 2. Conventional Commits 형식으로 커밋
git commit -m "fix(types): improve onMount option type definition

- Make onMount callback type more strict
- Prevent potential type errors
- Add test cases for type validation"

# 3. 포크한 저장소에 푸시
git push origin fix/onmount-type

# 4. GitHub에서 PR 생성
# - Base repository: pmndrs/jotai (main)
# - Head repository: YOUR_USERNAME/jotai (fix/onmount-type)
# - PR 템플릿에 따라 설명 작성

이북처럼 술술 읽히는 설명 김개발 씨는 타입 정의를 개선하는 코드를 완성했습니다. 테스트도 작성했고, 로컬에서 모든 테스트가 통과했습니다.

"이제 커밋하면 되는 거지?" 박시니어 씨가 고개를 젓습니다. "커밋 메시지가 정말 중요해요.

Jotai는 Conventional Commits를 따르니까 형식을 맞춰야 해요." PR 작성이란 무엇일까요? PR 작성은 마치 논문을 학회에 제출하는 것과 같습니다. 연구 결과만큼이나 중요한 것이 초록과 설명입니다.

아무리 좋은 코드를 작성해도 PR 설명이 부실하면 리뷰어가 의도를 이해하기 어렵습니다. 좋은 PR은 세 가지 요소로 구성됩니다.

첫째, 명확한 커밋 메시지. 둘째, 상세한 PR 설명.

셋째, 깔끔한 커밋 히스토리입니다. 커밋 메시지 작성하기 Jotai는 Conventional Commits 형식을 따릅니다.

이 형식은 type(scope): subject 구조로 이루어집니다. 김개발 씨가 작성한 커밋 메시지를 보겠습니다.

fix(types): improve onMount option type definition. 여기서 'fix'는 버그 수정을, '(types)'는 타입 관련 변경을 의미합니다.

본문에는 무엇을 왜 바꿨는지 구체적으로 적습니다. "타입을 더 엄격하게 만들었다", "잠재적인 타입 에러를 방지한다", "타입 검증 테스트를 추가했다" 같은 내용입니다.

PR 설명 작성하기 GitHub에서 PR을 생성하면 템플릿이 나타납니다. Jotai의 PR 템플릿에는 다음 섹션들이 있습니다.

What: 무엇을 변경했는지 간단히 설명합니다. "onMount 콜백의 타입 정의를 개선했습니다." Why: 왜 이 변경이 필요한지 설명합니다.

"기존 타입이 너무 넓어서 실수로 잘못된 값을 전달할 수 있었습니다." How: 어떻게 해결했는지 설명합니다. "제네릭 타입 제약을 추가하여 타입을 더 엄격하게 만들었습니다." Testing: 어떻게 테스트했는지 설명합니다.

"새로운 타입 테스트 케이스를 추가했고, 모든 기존 테스트가 통과합니다." 김개발 씨는 템플릿을 꼼꼼히 채워 넣었습니다. 코드 예제도 추가하여 변경 전후를 명확히 보여줬습니다.

Before: typescript // 타입이 너무 넓어서 실수 가능 onMount: (setAtom: any) => void After: typescript // 엄격한 타입으로 안전성 향상 onMount: (setAtom: SetAtom<T>) => void 커밋 히스토리 정리하기 작업하면서 "임시 커밋", "오타 수정", "다시 수정" 같은 커밋을 여러 개 만들었다면 어떻게 할까요? 박시니어 씨가 git rebase -i HEAD~3을 알려줍니다.

이 명령어로 최근 3개의 커밋을 하나로 합칠 수 있습니다. squash나 fixup을 사용하면 깔끔한 커밋 하나로 정리됩니다.

"메인테이너들은 깔끔한 커밋 히스토리를 선호해요. 'WIP' 같은 커밋은 PR에 포함시키지 마세요." CI 통과 확인하기 PR을 생성하면 자동으로 CI가 돌아갑니다.

린트 검사, 타입 체크, 테스트 실행 등이 자동으로 이루어집니다. 김개발 씨의 PR에도 초록색 체크마크가 뜨기 시작했습니다.

"모든 검사 통과!" 박시니어 씨가 엄지를 치켜세웁니다. "완벽해요.

이제 메인테이너의 리뷰를 기다리면 돼요." 실무 팁 많은 성공적인 기여자들은 PR을 보내기 전에 스스로 코드 리뷰를 합니다. GitHub의 "Files changed" 탭에서 자신의 변경사항을 처음 보는 사람의 시선으로 읽어봅니다.

"이 부분 설명이 부족한가?", "변수명이 명확한가?", "불필요한 변경은 없나?" 같은 질문을 던져봅니다. 이렇게 하면 리뷰어가 지적할 만한 사소한 문제들을 미리 잡을 수 있습니다.

주의사항 초보자들이 자주 하는 실수는 PR에 관련 없는 변경사항을 포함시키는 것입니다. "김에 이것도 고쳐야겠다"는 생각은 위험합니다.

하나의 PR은 하나의 목적만 가져야 합니다. 또한 PR 설명을 "코드 수정"처럼 대충 쓰면 안 됩니다.

리뷰어가 코드를 일일이 읽어가며 의도를 추측해야 하기 때문입니다. 정리하며 김개발 씨의 첫 PR이 드디어 생성되었습니다.

명확한 제목, 상세한 설명, 깔끔한 커밋으로 무장한 PR입니다. 박시니어 씨가 말합니다.

"좋은 PR은 리뷰어를 배려하는 PR이에요. 여러분의 PR이 그런 PR이 되길 바랍니다."

실전 팁

💡 실전 팁

• PR 제목은 50자 이내로, 본문 첫 줄은 72자 이내로 작성하세요
• 스크린샷이나 GIF로 UI 변경사항을 시각적으로 보여주면 좋습니다

---

5. 코드 리뷰 대응

2-3문장으로 상황 설정 PR을 보낸 지 하루가 지났습니다. 김개발 씨는 메일함을 열어보니 메인테이너로부터 코드 리뷰가 달려 있었습니다.

"이 부분을 이렇게 수정해 주시겠어요?" 떨리는 마음으로 리뷰를 읽기 시작합니다.

핵심 개념을 3-4문장으로 코드 리뷰 대응은 메인테이너의 피드백을 수용하고 코드를 개선하는 과정입니다. 마치 선생님의 첨삭을 받아 글을 다듬는 것과 같습니다.

긍정적인 태도로 피드백을 받아들이고, 명확하게 소통하며, 요청사항을 반영하는 것이 핵심입니다.

다음 코드를 살펴봅시다.

# 1. 리뷰 피드백 확인
# GitHub PR 페이지에서 Files changed 탭의 댓글 확인

# 2. 피드백 반영하여 코드 수정
# src/core/atom.ts 파일 수정

# 3. 수정사항 커밋 (fixup 사용)
git add src/core/atom.ts
git commit --fixup HEAD

# 4. 리베이스로 커밋 정리
git rebase -i --autosquash HEAD~2

# 5. Force push (주의: PR 브랜치에만 사용)
git push origin fix/onmount-type --force-with-lease

# 6. GitHub에서 리뷰어에게 답변
# "좋은 지적 감사합니다. 말씀하신 대로 수정했습니다."

이북처럼 술술 읽히는 설명 김개발 씨는 첫 코드 리뷰 알림을 받았습니다. 가슴이 두근거렸습니다.

"혹시 뭘 잘못했나?" 걱정 반 기대 반으로 댓글을 열어봤습니다. 메인테이너 daishi의 댓글이었습니다.

"좋은 PR이네요! 한 가지만 수정해 주시겠어요?

타입 파라미터 이름을 더 명확하게 해주세요." 박시니어 씨가 옆에서 안심시킵니다. "봐요, 친절한 피드백이잖아요.

오픈소스 메인테이너들은 생각보다 훨씬 친절해요." 코드 리뷰란 무엇일까요? 코드 리뷰는 마치 작가가 편집자로부터 원고 검토를 받는 것과 같습니다. 편집자는 작가를 비난하려는 것이 아니라, 더 나은 작품을 만들기 위해 조언하는 것입니다.

코드 리뷰도 마찬가지입니다. 메인테이너는 프로젝트의 코드 품질을 지키는 문지기입니다.

동시에 기여자를 돕는 멘토이기도 합니다. 그들의 피드백은 여러분을 성장시키는 소중한 자산입니다.

왜 코드 리뷰가 중요할까요? 과거 김개발 씨는 코드 리뷰를 부정적으로 받아들였습니다. "내 코드에 뭐가 문제라는 거지?"라며 방어적인 자세를 취했습니다.

그 결과 메인테이너와의 관계가 어색해지고, PR 머지가 늦어졌습니다. 하지만 태도를 바꾸고 나서는 달랐습니다.

"아, 이렇게 하면 더 좋아지는구나!" 하며 배우는 자세로 임했습니다. 메인테이너도 더 적극적으로 조언해 줬고, PR은 빠르게 머지되었습니다.

코드 리뷰는 단순히 코드를 개선하는 것을 넘어, 오픈소스 커뮤니티에서 관계를 쌓는 과정입니다. 피드백에 대응하는 방법 첫 번째 원칙은 빠르게 응답하기입니다.

메인테이너가 시간을 내서 리뷰해 줬다면, 24시간 이내에 답변하는 것이 예의입니다. "확인했습니다.

수정하겠습니다"라는 짧은 답변이라도 좋습니다. 두 번째 원칙은 명확하게 소통하기입니다.

피드백이 이해되지 않으면 정중하게 질문하세요. "이 부분을 좀 더 설명해 주실 수 있을까요?"라고 물어보면 됩니다.

세 번째 원칙은 감사 표현하기입니다. "좋은 지적 감사합니다", "배울 점이 많네요" 같은 긍정적인 태도는 리뷰어에게 힘을 줍니다.

코드 수정하기 김개발 씨는 메인테이너의 제안대로 타입 파라미터 이름을 T에서 Value로 변경했습니다. 훨씬 명확해졌습니다.

수정한 코드를 커밋할 때는 git commit --fixup HEAD를 사용합니다. 이렇게 하면 원래 커밋을 수정하는 fixup 커밋이 만들어집니다.

나중에 git rebase -i --autosquash로 깔끔하게 합칠 수 있습니다. Force Push 주의사항 커밋을 정리한 후에는 git push --force-with-lease로 푸시해야 합니다.

일반 push는 거부되기 때문입니다. 박시니어 씨가 경고합니다.

"절대로 main 브랜치에 force push하지 마세요. PR 브랜치에만 사용해야 해요." --force-with-lease는 다른 사람이 푸시한 내용을 실수로 덮어쓰지 않도록 보호해 줍니다.

--force보다 안전합니다. 논쟁이 필요한 경우 때로는 메인테이너의 의견에 동의하지 않을 수도 있습니다.

이럴 때는 어떻게 해야 할까요? 먼저 자신의 의견을 정중하게 설명합니다.

"이렇게 하면 X라는 문제가 있을 것 같은데, Y 방식은 어떨까요?" 기술적 근거를 들어 설명하면 좋습니다. 하지만 최종 결정은 메인테이너의 몫입니다.

그들이 프로젝트의 방향을 가장 잘 알고 있기 때문입니다. 동의할 수 없더라도 존중하는 태도를 유지하세요.

승인과 머지 몇 번의 수정을 거친 후, 드디어 메인테이너가 "LGTM(Looks Good To Me)"이라는 댓글을 달았습니다. 승인 마크도 떴습니다.

김개발 씨는 가슴이 벅차올랐습니다. 잠시 후 "Merged" 표시가 나타났습니다.

자신의 코드가 Jotai의 일부가 된 순간입니다. 실무에서의 리뷰 문화 성공적인 오픈소스 기여자들은 리뷰를 배움의 기회로 삼습니다.

유명 메인테이너로부터 받은 피드백을 노트에 정리해 두고, 다음 PR에 반영합니다. 또한 다른 사람의 PR 리뷰를 구경하는 것도 좋은 학습 방법입니다.

"저 메인테이너는 이런 부분을 중요하게 보는구나" 하며 프로젝트의 코드 철학을 배울 수 있습니다. 주의사항 초보자들이 자주 하는 실수는 리뷰 댓글에 즉각 반응하지 않는 것입니다.

일주일 후에 답변하면 메인테이너는 이미 다른 일로 넘어간 상태입니다. 또한 "나중에 수정하겠습니다"라고만 하고 실제로 수정하지 않는 것도 문제입니다.

약속한 수정은 반드시 실행하세요. 정리하며 박시니어 씨가 축하합니다.

"첫 PR 머지를 축하해요! 이제 당당한 Jotai 컨트리뷰터예요." 김개발 씨는 뿌듯함과 함께 자신감이 생겼습니다.

코드 리뷰는 두려운 것이 아니라 성장의 기회였습니다.

실전 팁

💡 실전 팁

• 리뷰 댓글에는 24시간 이내에 응답하세요
• 여러 번 수정 요청을 받더라도 긍정적인 태도를 유지하세요

---

6. 오픈소스 에티켓

2-3문장으로 상황 설정 첫 PR을 성공적으로 머지한 김개발 씨는 이제 오픈소스의 맛을 알았습니다. 하지만 박시니어 씨가 조언합니다.

"기술만큼이나 중요한 게 에티켓이에요. 커뮤니티 예의를 지켜야 환영받는 기여자가 될 수 있어요."

핵심 개념을 3-4문장으로 오픈소스 에티켓은 커뮤니티에서 다른 사람들과 협력하기 위한 예의와 규칙입니다. 마치 도서관에서 조용히 해야 하듯이, 오픈소스 커뮤니티에도 지켜야 할 불문율이 있습니다.

존중하는 태도, 명확한 소통, 인내심이 핵심입니다.

다음 코드를 살펴봅시다.

// 좋은 오픈소스 커뮤니케이션 예시

// ❌ 나쁜 예
// "이 버그 왜 안 고쳐요? 빨리 해주세요!"
// "이거 당연히 되어야 하는 거 아닌가요?"

// ✅ 좋은 예
// "안녕하세요! 이 이슈를 확인했는데요,
// X 상황에서 Y 에러가 발생합니다.
// 재현 방법을 아래에 정리했습니다.
// 제가 수정을 시도해봐도 될까요?"

const goodEtiquette = {
  // 정중하게 요청하기
  askPermission: "이 이슈를 제가 작업해도 될까요?",
  // 감사 표현하기
  showGratitude: "리뷰해 주셔서 감사합니다!",
  // 인내심 갖기
  bePatient: "메인테이너의 응답을 기다립니다"
};

이북처럼 술술 읽히는 설명 김개발 씨는 두 번째 이슈를 찾았습니다. 흥분한 마음에 바로 "제가 이거 하겠습니다!"라고 댓글을 달려고 했습니다.

박시니어 씨가 손을 멈춥니다. "잠깐만요.

먼저 이슈를 제대로 읽어보고, 이미 다른 사람이 작업 중인지 확인해야 해요. 무작정 달려드는 건 실례예요." 오픈소스 에티켓이란? 오픈소스 에티켓은 마치 공공장소에서의 예절과 같습니다.

도서관에서 큰 소리로 떠들면 안 되듯이, 오픈소스 커뮤니티에도 지켜야 할 암묵적인 규칙들이 있습니다. 메인테이너들은 무급으로 자신의 시간을 쪼개어 프로젝트를 관리합니다.

그들의 노고를 존중하고, 커뮤니티의 다른 구성원들과 협력하는 태도가 필수입니다. 왜 에티켓이 중요할까요? 과거 김개발 씨는 에티켓을 몰라서 실수한 적이 있습니다.

"이 기능 언제 추가되나요? 빨리 해주세요"라는 댓글을 달았다가 차갑게 무시당했습니다.

반대로 정중하게 "이 기능이 있으면 좋을 것 같은데, 제가 PR을 작성해도 될까요?"라고 물었을 때는 메인테이너가 친절하게 안내해 줬습니다. 오픈소스는 기술력만큼이나 인간관계가 중요합니다.

좋은 에티켓은 커뮤니티에서 환영받는 지름길입니다. 이슈 작성 에티켓 새로운 이슈를 작성하기 전에 반드시 검색부터 하세요.

이미 동일한 이슈가 있는데 중복으로 올리면 메인테이너의 시간을 낭비하게 됩니다. 이슈를 작성할 때는 재현 가능한 예제를 포함하세요.

"버그가 있어요"보다는 "A를 했을 때 B가 발생합니다. 재현 코드는 다음과 같습니다"가 훨씬 도움이 됩니다.

또한 환경 정보도 명시하세요. Node.js 버전, OS, 브라우저 등의 정보는 문제 해결에 필수적입니다.

댓글 작성 에티켓 이슈나 PR에 댓글을 달 때는 건설적인 내용만 작성하세요. "+1", "저도요" 같은 댓글은 노이즈입니다.

대신 이슈에 반응(thumbs up)을 남기세요. 반대 의견을 표현할 때는 공격적이지 않게 전달하세요.

"이 방법은 명백히 틀렸어요"보다는 "이런 방법도 고려해 볼 수 있을 것 같습니다"가 낫습니다. PR 에티켓 PR을 보낼 때는 작은 단위로 나누세요.

한 번에 수백 줄을 바꾸는 거대한 PR은 리뷰하기 어렵습니다. 가능하면 논리적으로 독립적인 작은 PR 여러 개로 나누세요.

또한 관련 없는 변경사항을 포함하지 마세요. "김에 이것도"는 금물입니다.

하나의 PR은 하나의 목적만 가져야 합니다. 기다림의 미학 메인테이너가 즉시 응답하지 않더라도 재촉하지 마세요.

그들도 바쁜 일상을 살아가는 사람들입니다. 김개발 씨는 PR을 보낸 후 3일 동안 응답이 없자 조급해졌습니다.

"혹시 제 PR 보셨나요?"라고 댓글을 달려다가 참았습니다. 박시니어 씨가 말합니다.

"일주일은 기다려 보세요. 그래도 응답이 없으면 정중하게 리마인드하는 건 괜찮아요." 감사 표현하기 메인테이너가 시간을 내어 리뷰해 줬다면 반드시 감사를 표현하세요.

"리뷰해 주셔서 감사합니다", "배울 점이 많았습니다" 같은 말 한마디가 그들에게 큰 힘이 됩니다. PR이 머지됐을 때는 더욱 그렇습니다.

"머지해 주셔서 감사합니다. 좋은 프로젝트에 기여할 수 있어 영광입니다"라고 마무리하세요.

다른 기여자 존중하기 때로는 같은 이슈에 여러 사람이 관심을 보일 수 있습니다. 먼저 작업 의사를 밝힌 사람이 우선권을 갖습니다.

만약 그 사람이 일주일 이상 진전이 없다면, "혹시 아직 작업 중이신가요? 제가 도와드릴 수 있을까요?"라고 정중하게 물어보세요.

실무에서의 에티켓 문화 유명한 오픈소스 프로젝트일수록 에티켓을 엄격하게 지킵니다. React, Vue, TypeScript 같은 대형 프로젝트는 Code of Conduct(행동 강령) 문서를 따로 둘 정도입니다.

이런 프로젝트에 기여하다 보면 자연스럽게 좋은 협업 문화를 배우게 됩니다. 이 경험은 나중에 팀 프로젝트나 회사 업무에서도 큰 자산이 됩니다.

주의사항 초보자들이 자주 하는 실수는 "급해요", "빨리 해주세요" 같은 표현을 쓰는 것입니다. 오픈소스는 무료 서비스가 아닙니다.

메인테이너에게 의무를 요구할 권리는 없습니다. 또한 메인테이너와의 논쟁에서 감정적으로 대응하는 것도 금물입니다.

기술적 토론은 환영받지만, 인신공격은 절대 안 됩니다. 정리하며 박시니어 씨가 마무리합니다.

"오픈소스는 코드만큼이나 사람이 중요한 세계예요. 좋은 에티켓은 여러분을 환영받는 기여자로 만들어 줄 거예요." 김개발 씨는 고개를 끄덕입니다.

이제 자신도 Jotai 커뮤니티의 일원이 된 기분입니다. 다음 기여가 벌써 기대됩니다.

실전 팁

💡 실전 팁

• 이슈나 PR에 댓글을 달기 전에 한 번 더 읽어보며 공손한지 확인하세요
• 메인테이너의 응답을 최소 3-5일은 기다린 후 리마인드하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!