soulee.dev

오픈소스 컨트리뷰션 아카데미 - (1) Node.js 환경 구축하기

· 12 min read
osscaopensourcenodejs

오픈소스 컨트리뷰션 아카데미는 2023년에 처음 python-mysql-replication 프로젝트로 접하여 군 입대 직전에 우수상을 수상하였다.

이후에 군에서 전역을 하고, 한동안 회사생활에 치여 살았다. 어느정도 안정을 잡고 나니, AI로 인해 머리가 굳어가는게 느껴졌다. 오랜만에 머리를 부여잡고 새로운 사람들을 만나 새로운 도전을 해보고 싶었고, 그래서 2026 오픈소스 컨트리뷰션 아카데미에 Node.js로 지원하였다.

지원 후 운좋게도 합격하게 되었고, 발대식에 참여하게 되었다. 이번 발대식도 OSSCA가 늘 그렇듯 과학기술회관에서 이루어졌고, 첫날부터 다양한 분들과 이야기를 나눌수 있어서 좋았다.

특히 V8 엔진 등 관심사가 있는 부분에 대해 이야기를 나누었고, Node.js 가 Platform-agnostic하게 사용 가능한 웹 기술이라는 내용도 매우 공감 되었다.

AI를 사용한 기여에 대해서도 서로 이야기를 나누었는데 경험상 머리를 써서 고생한것만 기억에 남는것 같아서, 나또한 Code generation은 AI의 도움을 받고, 전반적인 프로젝트의 구조에 대해서는 내가 직접 이해를 해보려고 노력하며 진행하려고 한다.

아직까지 고정적으로 기여하는 오픈소스 프로젝트는 없지만, 이 기회에 Node.js 같은 프로젝트에서 자리를 잡아보고 싶기도 하다.

OSSCA에서 Node.js를 선택한 이유는,

  1. 우선 내가 일상적으로 쓰고 있는 기술들의 내부를 알고 싶었다.
  2. C++같은 Low level 언어를 좋아하는데, High level 언어만 너무 해서 리프레시 하고 싶었다.
  3. 그나마 후보군에 있었던 Chromium은 gerrit이라는 자체 Git을 쓰고 Issue tracking 도 자체 플랫폼에 종속되어, GitHub에 뜨지 않는 점이 아쉬웠다.
  4. 마지막으로 사람들이 많이 사용하는 오픈소스에 기여하여 조금이나마 세상에 도움을 주고 싶었다.

오픈소스에 기여하기 전 가장 먼저 해야할건 README.md를 읽어서 개요를 살피고, Contribution 문서 (보통은 CONTRIBUTING.md)를 살펴보는것이다.

특히나 큰 규모의 프로젝트들은 자체적인 거버넌스/합의를 갖고 있거나 메일링 리스트처럼 구조를 갖고 있는 경우가 있기때문에 필수적으로 봐야한다.

아래 내용은 2026.7.11 기준으로, 현재와 다를수 있습니다.

CONTRIBUTING.md

CONTRIBUTING.md를 Heading 순서대로 요약하자면

  • Code of Conduct (CoC) — 행동 강령
    • 큰 내용은 없지만, 규모 있는 오픈소스 프로젝트에는 다 있는것 같다.
    • 서로 언어나 행동을 조심하자는 내용이다.
    • 전세계 사람과 함께하는 커뮤니티 활동인 만큼 스스로 조심하자!
  • Issues
    • Bug reporting 등 Issue를 올리는 방법에 대한 내용이다.
  • Pull Requests — 여기서 우리가 가장 집중해서 살펴볼 내용들이 나온다.
    • Dependencies
      • 요즘은 의존성/라이브러리를 워낙 많이 쓰다 보니, 이게 무슨 문제냐 싶을수도 있다.
      • 하지만 Node.js는 수십억 device에 깔리는 프로젝트다. Supply chain attack(xz 백도어 사례)처럼 관리되지 않은 의존성 하나가 그대로 취약점이 된다.
      • 그래서 새 의존성은 Consensus와 Requirements를 모두 만족해야 추가할 수 있다. 커뮤니티 합의를 거쳐야 하는 지루한 과정이라, 가급적 지양하는게 좋다.
    • Setting up your local environment
      • 로컬 환경 셋팅 방법. 아래에서 따로 다루겠다.
    • The Process of Making Changes
      • 어디를 고치면 될지 감사하게도 알려준다.
        • src — C/C++ 코드
        • lib — JavaScript
        • doc/api — 문서
        • test — 테스트
      • 코드를 수정했다면 make lint(윈도우는 vcbuild.bat lint)로 Node.js code style 가이드에 맞춰야 한다.
      • 커밋 메시지 가이드라인도 있다.
        • 첫 줄에는 짧은 설명을 쓰고, 고유명사/약어/함수명 빼고는 소문자로 쓴다.
        • 어떤곳을 고쳤는지 (lib / src / doc / build / test / tools) 접두사를 붙인다.
        • 이슈를 고치는 거면 끝에 Fixes: 전체이슈URL, 참고면 Refs: 를 추가한다.
        • 예) src: fix typos in async_wrap.h, net: add localAddress and localPort to Socket
        • 가장 중요한 건 DCO다. Node.js 프로젝트의 약관?에 동의하는거라고 보면 된다. git commit -s 로 붙일 수 있다. 이후 기여를 진행할때 기록해보겠다.
        • 그 외에도 몇가지 더 있으니 한번 직접 확인해보면 좋을듯 하다.
    • Reviewing Pull Requests
      • Collaborator 2명 이상의 승인이 필요하다. 다만 PR이 7일 넘게 열려있었다면 1명으로도 충분하다.
      • CI가 통과해야한다.
      • 승인 + CI를 통과하더라도 최소 48시간 동안 Open되어있어, 모두가 의견을 낼 기회를 보장한다. trivial한 변경은 예외이다.
    • 좋은 이야기들이 많은데, 우선 프로젝트를 진행하면서 하나씩 살펴보면 좋을듯 하다.

CONTRIBUTING.md를 읽은 다음으론 멘토님께서 말씀해주신 Node.js 개발환경 설정을 준비했다.

Node.js 빌드 환경 설정

나는 OSSCA 시작하기 전에 Node.js의 분위기를 알아보기 위해 AI 도움 받아 간단한 기여(testing 에러 수정)을 했다. 아쉽게도 처음 PR을 올린 사람이 메인테이너의 요청에 빨리 처리하지 않아, 내 PR이 선택되진 않았다.

당시에는 Mac환경이여서 쉬웠지만, 이번에는 Windows 환경에 구축하면서 Trial & Error을 거치며 빌드 환경 설정을 완료하였다.

이번에는 BUILDING.md 문서를 기준으로 Node.js를 clone 하고, 환경설정 / lint 및 빌드까지만 해보는걸 목표로 한다. 기여를 하기 위해서는 fork를 해야하지만, 이 단계에서는 clone하는 것까지만 해본다.

Windows에서는 많은 의존성이 필요해 환경설정이 어려워지는 관계로, WSL 환경 (Ubuntu 20.04 LTS)를 이용해보겠다. 참고로 WSL은 Microsoft Store에서 쉽게 설치할수 있다.

Bash
git clone https://github.com/nodejs/node.git

용량은 1.5GB로 시간이 좀 걸린다.

Node.js에서는 Makefile을 사용한다. Makefile은 쉽게 말해 빌드/테스트 등에 필요한 명령어들을 모아놓은 파일이다. 예를 들면 make lint 라는 명령어 하나를 실행하면 여러줄의 스크립트를 알아서 실행해준다.

Bash
cd node
make lint

위 명령어를 돌리면 시간이 꽤 걸린다.

Bash
./configure

위 명령어를 실행하면 Python script(configure.py)를 이용해 환경 설정을 해준다.

Bash
make -j4
text
WARNING: C++ compiler (CXX=g++, 9.4.0) too old, need g++ 13.2.0 or clang++ 19.1.0
WARNING: warnings were emitted in the configure phase

Warning이라 문제 없을줄 알고 실행시키니깐 문제가 발생했다

text
g++: error: unrecognized command line option '-std=gnu++20'; did you mean '-std=gnu++2a'?

c++20이 필요한데 지금 g++가 너무 구버전(9.4.0)이다. 업데이트 하자

Bash
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
 
sudo apt update
 
sudo apt install g++-15 gcc-15
 
 
export CC=gcc-15
export CXX=g++-15

다시 빌드를 해본다

Bash
# CPU 성능에 따라 숫자를 올려서 병렬빌드할수있다. 나는 16으로 했다. CPU 사용률을 70~80왔다갔다 하는 정도
make -j4
text
compilation terminated.
make[1]: *** [tools/v8_gypfiles/v8_compiler.target.mk:404: /home/soulee/workspace/node/out/Release/obj.target/v8_compiler/deps/v8/src/compiler/pipeline.o] Error 1
make[1]: *** Waiting for unfinished jobs....
rm f7576c8029663a1d6bba76a58f286ba673ede29edc6fb4f1be8f7f2dfa8ab956.intermediate 2815f680cdfa33982372d2cedc4977b98f67aebb3b64840abcb362029ee76162.intermediate 74dcce3b650a825c4950f3679dc57e7a59ef692b5060c297f6525e948127ef70.intermediate bd57dfef2eb061cd4b310dd8da57f8f3e9edbe25dee1fdbd4586b79f6db15113.intermediate
make: *** [Makefile:143: node] Error 2
real    7m49.344s
user    108m19.404s
sys     6m34.218s

에러가 발생했다. claude에 물어보니 병렬 빌드를 너무 많이 걸어서 OOM이라고 한다. make -j8로 바꿔서 하니 문제없이 잘 돌아갔다.

처음 빌드하면 오래 걸린다. time 명령어로 측정해보니 49분 걸렸다. 이후부터는 증분 빌드가 적용되어 빠르게 빌드가 진행된다.

이제 빌드한 내용을 기반으로 테스트를 돌려보자.

Bash
make test
Bash
All tests passed.
 
real    40m43.348s
user    49m41.543s
sys     10m43.577s

위 문구가 나오면 테스트도 완료되었다.

마치며

지금까지 오픈소스 기여를 해보면서 배운 점은

  • good first issue 태그가 붙은 이슈부터 찾아본다. Maintainer들이 초보자도 쉽게 할수 있는 이슈에 달아주는 태그다.
  • 다른 사람이 assign 되어 하고 있지는 않은지 확인한다. 아니라면 issue 등에 내가 맡겠다고 말한다.
  • 이미 다른 사람이 assign 되어있다면, review를 같이 해주거나 내가 했던 것 처럼 틀린 부분을 도와주면 좋은거 같다.
  • 가장 중요한 건 화면 너머에 있는 사람(Maintainer)과 라포를 형성하는 것이라고 생각한다. 결국에는 이것도 다 사람이 하는것 이기때문이다.