오픈소스 기여, 환경 구축부터 디버깅까지

조회수 ...회

오픈소스 밥상차리기: 환경설정과 디버깅편

목표 청중

처음으로 오픈 소스에 기여를 해보고 싶은 프론트엔드 개발자
시도는 해보았지만 환경 구축과 디버깅에 어려움을 느낀 개발자
평소 오픈소스 코드로 학습을 해보고 싶은 개발자

발표 목표

오픈 소스 코드를 읽는 것이 왜 유익한지 알린다.
오픈 소스 코드를 읽는 구체적이고 실용적인 방법을 제시한다.
오픈 소스에 코드를 기여 하는 것에 두려움을 느끼지 않고 흥미로워 지도록 한다.
청중이 직접 오픈 소스를 살펴보고 싶도록 만든다.

들어가며
왜 오픈 소스를 읽어야 할까?
1. 내가 사용하는 도구의 내부 동작 이해
2. 문제 해결 능력 향상 (다양한 코드 스타일 접하기)
3. 최신 기술 및 베스트 프랙티스 학습
4. 커뮤니티 기여의 첫걸음
주니어 프론트 입장에서 어떤 오픈소스가 좋을까?
개발환경 구축 및 디버깅
- CONTRIBUTING.md을 정독 하자
- 개발환경 구축
  - package.json 파악하기
    - 사용하는 패키지매니저와 버전 확인
    - 필요한 스크립트 찾아서 실행해보기 (안 되는게 있으면 다시 CONTRIBUTING에 살펴보기)
- 디버깅
  - 프로젝트 성격에 맞는 디버깅 툴 파악하기 (jest, storybook, etc...)
  - 실전 예제 몇가지 준비
    - 어려움: next.js 살펴보기
    - 쉬움: mantin, react-hook-form
마무리

들어가며

"오픈소스에 기여하고 싶은데 어디서부터 시작해야 할지 모르겠어요." (슬라이드)

이 말을 주변 개발자들에게 정말 많이 들었습니다.
사실 저도 불과 몇 달 전까지는 똑같은 고민을 하고 있었습니다. GitHub에서 유명한 프로젝트를 clone 받아보려 했지만, 수천 개의 파일과 복잡한 설정에 압도되어 조용히 창을 닫곤 했죠.

그러다 업무 중에 React Hook Form의 useWatch 함수가 예상과 다르게 동작하는 상황을 만났습니다. 공식 문서만으로는 이해가 안 되서 결국 GitHub에서 해당 함수의 구현을 찾아보게 되었죠. 그때 깨달았습니다.
"아, 거대한 프로젝트 전체를 이해하려고 하지 말고, 내가 궁금한 부분만 찾아보면 되는구나!"

우리는 매일 수십 개의 오픈소스 라이브러리를 사용합니다. npm install로 설치하고, import해서 쓰고, 문서를 보며 API를 익힙니다. 하지만 정작 그 안에 어떤 코드가 들어있는지는 거의 들여다보지 않습니다.

왜 오픈소스 코드를 읽어야 할까요? (슬라이드)

"이 기능이 왜 이렇게 동작하지?" - 문서에 없는 답이 코드에 있습니다
"이렇게 구현하는구나!" - 실력 있는 개발자들의 코드를 무료로 볼 수 있는 기회입니다 ex) 모노레포구성, 디자인 시스템 구성, 테스트 코드 구성
"어, 이건 버그 아닌가?" - 코드를 읽다 보면 자연스럽게 개선점이 보입니다
"나도 할 수 있겠는데?" - 생각보다 특별하지 않은 코드들이 많습니다

저는 React Hook Form의 useWatch 함수가 어떻게 구현되어 있는지 궁금해서 코드를 열어본 것이 시작이었습니다.
복잡할 것 같았던 내부 구현이 생각보다 읽을 만했고, 그러다 관련 이슈를 찾고 수정할 수 있었습니다.
오늘은 제가 실제로 오픈소스 프로젝트를 로컬에서 실행하고, 버그를 찾아 수정하기까지의 과정을 단계별로 공유하려 합니다.
특별한 기술이나 경험이 없어도 충분히 따라할 수 있도록 최대한 쉽게 설명해보겠습니다.

왜 오픈 소스를 읽어야 할까?

내가 사용하는 도구의 내부 동작 이해
1. 내감이 틀리지 않았다. 공식 문서 찾거나 github issues 찾고 살펴본다.
최신 기술 및 베스트 프랙티스 학습
1. 모노레포 및 디자인 시스템 구성 방법 찾을 수 있다. 기타 하고 싶었던 구성을 오픈소스에 너무나도 잘 되어 있다. 예시 보여주기
2. 테스트 코드 작성 방법 및 구성 하는 방법을 배울 수 있다 ex) next.js production 환경 테스트 코드 구성
문제 해결 능력 향상
1. 다양한 이슈를 접하고 풀어가는 경험을 할 수가 있다.
커뮤니티 기여의 첫걸음
자신감이 넘쳐 흐릅니다!

주니어 입장에서 어떤 오픈소스가 좋을까? (슬라이드)

나에게 맞는 프로젝트 찾기
- 관심 분야/주력 기술: 내가 자주 사용하고 잘 아는 라이브러리/프레임워크부터 시작하세요. (예: "저는 프론트엔드 개발자로서 평소 자주 사용하던 UI 라이브러리인 Mantine과 폼 관리 라이브러리인 React Hook Form을 선택했습니다.")
- 프로젝트 규모/활성도: 처음에는 너무 거대하지 않거나, 혹은 문서화가 잘 되어 있고 커뮤니티가 활발한 프로젝트가 좋습니다. (이슈, PR 활발 여부 확인)
첫 걸음
- README.md 정독
- CONTRIBUTING.md 정독
- 폴더 구조 훓어보기
- 이슈 목록 살펴보기: 다른 사람들이 어떤 문제를 보고하고 있는지 확인하세요.

개발 환경 구축

package.json 읽기
- 사용하는 node version 확인
- 사용하는 Package Manager 확인 ex) npm, pnpm, yarn, etc...
- 전체 프로젝트 구조 파악 ex) 모노레포, 모놀로그
CONTRIBUTING.md 정독
- 설명대로 하나 하나 명령어를 실행해 보기 (예시로 react-hook-form/mantine 개발 환경 구축 사례)

자주 발생하는 환경 구축 문제와 해결책

목표: node_modules 성공적으로 설치하기

노드 버전 불일치
- 문제: "This module requires Node.js version X.Y.Z"
- 해결: nvm을 사용하여 필요한 Node 버전 설치
```
nvm install 20
nvm use 20
```
패키지 매니저 충돌
- 문제: yarn.lock이 있는데 npm으로 설치할 때 발생하는 의존성 문제
- 해결: 프로젝트에서 지정한 패키지 매니저만 사용하기
```
# corepack을 사용하여 yarn 활성화
corepack enable
```
모노레포 세팅 문제
- 문제: 특정 패키지만 빌드하려고 할 때 의존성 오류
- 해결: 루트 디렉토리에서 모든 의존성 설치 후 진행
```
pnpm install
```

디버깅

CONTRIBUTING/README 정독
1. 스토리북/jest 실행 하는 방법 찾기
  1. package.json 에서 관련 스토리북 / jest 사용 스크립트 찾기
  2. 빌드가 필요하면 관련 스크립트 찾기
  3. 하나씩 실행 시켜보면서 의도한 동작대로 움직이는지 파악
  4. ai에게 package.json, README, CONTRIBUTING를 학습 시켜서 물어보기 ex) 파일을 학습 시킨 후, 이 이슈에 대한 테스트 코드를 어디에 작성하고 어떻게 실행 시키는지 알려줘 react-hook-form 사례로 알려주기
2. 스토리북/jest를 찾았다!
  1. 구축된 다른 코드를 보면서 적당한 곳에 끼워놓고 개발 시작

효과적인 디버깅 전략

해당 이슈를 정독후 문제를 재현해보자.
1. 가능 하면 테스트 코드나 storybook로 구현해 보기
2. 작성하기 어렵다면 다시 CONTRIBUTING에 살펴보기 or 다른 테스트 코드 비교해보기
3. 실행하는 스크립트를 찾아 실행해보기 With Ai 간편해 보이는 코드? or 어려워 보이는 코드?
4. 이슈에서 힌트 찾기, 의심가는 파일의 git history 살펴보기

재현은 테스트 코드로 해보자

코드 탐색 팁

// 1. 관심 있는 컴포넌트에 console.log 추가
export const Select = props => {
  console.log('Select rendered with props:', props);
  // ...
};

// 2. debugger 구문 활용
const handleChange = newValue => {
  debugger; // 브라우저 개발자 도구에서 중단점 역할
  onChange(newValue);
};

// 3. Breakpoint 활용

// 4. React DevTools 활용
// - 컴포넌트 트리 확인
// - Props/State 실시간 확인
// 5. 성능 프로파일링

마무리 및 Q&A

오픈 소스의 세계는 누구에게나 열려있습니다. 처음에는 거대한 코드베이스와 복잡한 환경 설정이 두렵게 느껴질 수 있습니다. 하지만 한 걸음씩 차근차근 나아가다 보면, 그리 어렵지 않다는 것을 깨닫게 될 것입니다.

여러분이 오늘 이 발표에서 꼭 기억해 가셨으면 하는 세 가지 핵심 메시지입니다:

시작이 반이다: 첫 PR은 어렵지만, 그 다음부터는 훨씬 쉬워집니다.
작은 것부터: 문서 오타 수정, 간단한 버그 수정처럼 작은 것부터 시작하세요.
커뮤니티의 힘: 질문하고, 배우고, 공유하는 과정에서 성장합니다.

여러분의 작은 기여가 전 세계 개발자들이 사용하는 도구를 개선하는데 도움이 될 수 있습니다. 내가 발견한 버그를 고치고, 새로운 기능을 제안하고, 문서를 개선하는 모든 활동이 소프트웨어 생태계를 더 풍요롭게 만듭니다.

다음 단계

오늘 발표를 듣고 실천할 수 있는 구체적인 다음 단계입니다:

자주 사용하는 라이브러리 하나를 선택해 GitHub 저장소 살펴보기
문서 개선이나 간단한 버그 수정으로 첫 PR 만들어보기
오픈소스 기여자 모임이나 온라인 커뮤니티에 참여하기

이제 여러분의 차례입니다. 관심 있는 프로젝트를 찾아보고, 코드를 읽어보고, 작은 것부터 시작해보세요. 그 과정에서 얻게 되는 배움과 성장, 그리고 기여의 즐거움을 직접 경험하시기 바랍니다.