오픈소스·데이터·벤치마크로 기여하기

오픈소스 기여

왜 필요한가. 연구 중에 쓰는 라이브러리에서 버그를 만나거나 문서가 틀린 것을 발견하는 일은 흔하다. 대부분은 자기 코드에서 우회하고 지나간다. 그러면 같은 문제를 다음 사람도 겪는다. 작은 수정이라도 원 프로젝트에 돌려보내면 문제가 공동체 전체에서 사라지고, 자신은 그 프로젝트의 코드와 관행을 깊이 이해하게 된다. 유지보수자(maintainer)와의 리뷰는 연구 코드에 대한 가장 직접적인 피드백이기도 하다.

자기 저장소와 남의 저장소는 다르다. 4.2장(GitHub 협업과 저장소 관리)에서 PR과 리뷰를 자기 팀의 저장소 기준으로 다뤘다. 남의 프로젝트에 기여할 때는 세 가지가 다르다.

• 쓰기 권한이 없다. 저장소를 자기 계정으로 복사한 fork에 branch를 만들고, 거기서 원 저장소(흔히 upstream이라 부른다)로 PR을 보낸다.
• 유지보수자의 시간이 가장 비싼 자원이다. 많은 과학 오픈소스는 소수의 연구자가 본업 외의 시간에 유지한다. 리뷰하기 쉬운 PR이 받아들여진다.
• 프로젝트마다 규칙이 있다. 코드 스타일, 테스트 방식, 커밋 메시지 형식, 기여자 동의 절차가 다르다. 이 규칙은 대개 CONTRIBUTING.md에 있다.

기여의 흐름. 처음 기여하는 프로젝트에서는 다음 순서를 따른다.

1. 기여 가이드를 읽는다. CONTRIBUTING.md, CODE_OF_CONDUCT.md, PR 템플릿, 개발 환경 설정 문서. 일부 프로젝트는 기여자 라이선스 동의(CLA)나, 커밋에 Signed-off-by 줄을 붙이는 DCO(Developer Certificate of Origin)를 요구한다. git commit -s가 이 줄을 붙인다.
2. 이슈를 먼저 찾고, 없으면 연다. 같은 문제가 이미 보고되었는지 검색한다. 작은 오탈자가 아닌 변경(동작 변경, 새 기능, 큰 리팩터링)은 PR보다 이슈로 먼저 제안해 방향에 합의한다. 몇 주 걸려 만든 PR이 "이 방향은 원하지 않는다"로 닫히는 일을 막는다.
3. 작게 시작한다. 문서 수정, 버그를 재현하는 테스트 추가, 작은 버그 수정이 좋은 첫 기여다. 많은 프로젝트가 처음 기여하는 사람에게 맞는 이슈에 good first issue 같은 label을 붙인다.
4. PR 하나에 목적 하나. 버그 수정에 관련 없는 서식 정리를 섞지 않는다. 리뷰어가 diff를 보고 목적을 바로 알 수 있어야 한다.
5. 테스트와 함께. 버그 수정이라면 수정 전에는 실패하고 수정 후에는 통과하는 테스트를 함께 보낸다(6.6장). 그 테스트가 "버그가 있었다"와 "고쳐졌다"의 증거다.
6. 리뷰에 응답한다. 댓글마다 고치거나, 고치지 않는 이유를 답한다. 리뷰가 늦어지면 1–2주 뒤 정중하게 한 번 묻는다. 받아들여지지 않은 PR도 이슈에 남은 논의로 다음 사람에게 도움이 된다.

fork에서 PR을 보내기까지의 명령은 대략 다음과 같다(집필 시점 예시. 저장소 주소와 기본 branch 이름은 프로젝트에서 확인한다).

# 1. 자기 계정의 fork를 내려받고, 원 저장소를 upstream으로 등록한다
git clone https://github.com/<내 계정>/<프로젝트>.git
cd <프로젝트>
git remote add upstream https://github.com/<원 소유자>/<프로젝트>.git

# 2. 원 저장소의 최신 기본 branch에서 작업 branch를 만든다
git fetch upstream
git switch -c fix-unit-conversion upstream/main

# 3. 수정하고, 프로젝트의 테스트를 돌린 뒤 fork로 push한다
git commit -s -m "Fix kelvin-to-celsius offset in temperature loader"
git push -u origin fix-unit-conversion
# 4. 호스팅 서비스 화면에서 fork의 branch → upstream의 main으로 PR을 연다

좋은 버그 보고. 코드 기여가 아니어도 좋은 버그 보고는 큰 기여다. 유지보수자가 문제를 자기 컴퓨터에서 재현할 수 있어야 고칠 수 있다. 좋은 보고는 다음을 담는다.

• 최소 재현 예제. 자기 프로젝트 전체가 아니라, 문제를 일으키는 가장 작은 코드(대개 20줄 이내)와 그 코드가 쓰는 작은 입력. 데이터가 필요하면 무작위 배열이나 라이브러리 내장 데이터로 바꾼다.
• 기대한 결과와 실제 결과. 오류라면 전체 traceback을 텍스트로 붙인다. 화면 캡처만으로는 검색도 복사도 할 수 없다.
• 환경. 운영체제, Python과 관련 패키지의 버전, 설치 방법(pip, conda 등). 많은 라이브러리가 버전 정보를 출력하는 함수나 명령을 제공한다. 이슈 템플릿이 있으면 그 항목을 따른다.

최소 재현 예제를 만드는 과정 자체가 디버깅이다. 코드를 줄이다 보면 문제가 라이브러리가 아니라 자기 코드에 있었다는 것을 발견하는 경우가 많다. 그것도 좋은 결과다.

데이터셋 공개

왜 필요한가. 과학 ML에서 공개 데이터셋은 연구의 출발점이자 비교의 기준이다. 잘 공개된 데이터셋 하나는 수많은 후속 연구를 가능하게 하지만, 문서·라이선스·버전이 없는 데이터셋은 쓰는 사람마다 다르게 해석하고, 결과를 서로 비교할 수 없게 만든다. 데이터를 내려받을 수 있게 하는 것과, 다른 사람이 올바르게 쓸 수 있게 하는 것은 다른 일이다.

공개 전 점검. 데이터를 공개하기 전에 네 가지를 확인한다. 앞의 둘은 23.12장에서, 뒤의 둘은 15.5장(데이터셋 버전·문서화·라이선스)에서 자세히 다뤘다.

라이선스. 남의 데이터로 만든 파생 데이터셋은 원 데이터의 조건을 따른다. 전처리했다고 새 데이터가 되지 않는다. 원 데이터가 비상업(NC) 조건이면 파생 데이터셋도 그 조건을 벗어날 수 없고, 동일조건(SA) 조건이면 같은 라이선스로 공개해야 한다. 자기가 만든 데이터라면 Creative Commons 계열(예: CC BY, CC0)이 흔히 쓰인다(집필 시점 예시. 조건은 라이선스 원문에서 확인한다). 코드와 데이터의 라이선스는 따로 붙인다.

저장소 선택. 데이터를 어디에 둘지는 데이터를 찾고 오래 쓰는 데 큰 차이를 만든다. 개인 웹페이지나 클라우드 드라이브 링크는 연구실을 옮기거나 계정을 정리하면 사라진다.

용량 제한, 접근 통제 기능, 보관 기간 정책은 저장소마다 다르고 바뀐다. 공개 전에 각 저장소의 문서에서 확인한다. FAIR 원칙(찾을 수 있고, 접근할 수 있고, 상호 운용되고, 재사용할 수 있게)이 저장소를 고르는 기준이 된다(Wilkinson 외, 2016).

영구 식별자. 논문에 데이터 위치를 URL로만 적으면 링크는 깨지고, 같은 URL이 가리키는 내용이 바뀔 수 있다. DOI(Digital Object Identifier) 같은 영구 식별자(persistent identifier)는 특정 대상의 특정 버전을 가리키고, 저장 위치가 바뀌어도 식별자가 새 위치로 연결되도록 관리된다. 범용 연구 데이터 저장소의 다수는 업로드한 데이터의 버전마다 DOI를 발급한다. 데이터를 고치면 새 버전으로 올리고 새 DOI를 받는다. 이미 발표된 논문은 옛 DOI로 옛 버전을 계속 가리킨다.

같은 원리가 코드에도 적용된다. Git 저장소의 branch는 움직이므로, 논문에 인용하는 코드는 release(태그)로 고정하고 보관 저장소에 아카이브해 식별자를 받는다. 일부 데이터 저장소는 코드 호스팅 서비스의 release를 자동으로 아카이브하는 연동 기능을 제공한다(집필 시점 예시. 저장소 문서에서 확인한다). 저장소 루트의 CITATION.cff(6.7장)에 이 식별자를 적어 두면 인용하는 사람이 정확한 버전을 인용할 수 있다.

벤치마크 설계

왜 필요한가. 벤치마크(benchmark)는 공동체가 방법을 비교하는 공통의 시험이다. 잘 설계된 벤치마크는 분야의 진척을 측정 가능하게 만들지만, 잘못 설계된 벤치마크는 공동체 전체를 엉뚱한 방향으로 최적화하게 만든다. 벤치마크는 데이터셋에 과제 정의, 분할, 지표, baseline, 평가 절차를 더한 것이다. 각각이 과학적 질문과 어긋나지 않는지가 설계의 핵심이다.

과제 정의. 먼저 "이 벤치마크에서 이긴 방법은 과학적으로 무엇을 할 수 있게 되는가"를 한 문장으로 쓴다. 예를 들어 "처음 보는 골격의 분자에 대해 물성을 예측할 수 있다"가 목적이라면, 과제의 입력·출력·분할이 모두 이 문장에서 나와야 한다.

분할. 분할은 벤치마크가 무엇을 재는지 정한다. 무작위 분할은 "이미 본 것과 닮은 것"에 대한 성능을, 분야의 묶음 단위(셀, 지역·연도, 골격, 서열 클러스터) 분할은 "처음 보는 것"에 대한 성능을 잰다(31.1장 프로젝트 D). 실제 사용 상황에 맞는 분할을 주 분할로 정하고, 분할 파일을 데이터와 함께 배포해 모두가 같은 분할을 쓰게 한다. 실제 분포 이동을 담은 데이터셋 모음으로 도메인 내·밖 성능 차이를 함께 보고하게 한 WILDS가 이런 설계의 예다(Koh 외, 2021). 학습 데이터와 테스트 데이터 사이의 중복·근사 중복은 배포 전에 검사한다. 벤치마크에 숨은 누수는 그 벤치마크를 쓰는 모든 논문으로 퍼진다(Kapoor & Narayanan, 2023).

지표. 주 지표 하나와 보조 지표 몇 개를 정하고, 정의를 코드로 배포한다. "RMSE"라는 이름만으로는 단위 변환, 평균을 내는 단위(샘플별인지 그룹별인지), 결측 처리가 정해지지 않는다. 과학적으로 중요한 실패(물리적으로 불가능한 예측, 극값에서의 오차)가 평균 지표에 묻히면 그것을 따로 재는 지표를 둔다.

baseline. 단순 baseline과 강한 baseline을 실행 가능한 코드로 함께 배포한다(16.1장). baseline 코드가 없으면 후속 논문마다 baseline을 다르게 구현하고, 약하게 튜닝된 baseline 대비 개선이 쌓인다.

리더보드의 함정. 공개 리더보드는 경쟁을 만들고, 경쟁은 몇 가지 함정을 만든다.

• 테스트 데이터에 대한 적응적 과적합. 같은 테스트 데이터에 여러 번 제출해 점수를 보고 방법을 고치면, 테스트 데이터가 사실상 검증 데이터가 된다. 공개 테스트와 비공개 테스트를 나누거나, 제출 횟수를 제한하는 장치가 이를 줄인다.
• 잡음보다 작은 차이로 순위를 매기는 것. 테스트 표본 수가 유한하므로 점수 자체가 추정값이다. 정확도 $p$를 $n$개의 독립 표본으로 잴 때 표준오차는 대략 $\sqrt{p(1-p)/n}$다. $p = 0.9$, $n = 1000$이면 약 0.0095, 즉 0.95%p다. 두 방법을 같은 테스트 데이터로 비교할 때는 짝지은 비교가 필요하므로 차이의 불확실성은 이 값과 다르지만(12.5장), 0.2%p 차이로 매긴 순위가 의미 있는지는 따져 봐야 한다. seed에 따른 변동까지 더하면 더 그렇다.
• 보고되지 않은 비용. 튜닝에 쓴 계산량과 하이퍼파라미터 탐색 횟수가 방법마다 크게 다르면, 순위는 방법이 아니라 튜닝 예산을 비교한 것이 된다. 제출 양식에 계산 예산과 탐색 횟수를 적게 한다.
• 지표와 과학적 목적의 괴리. 지표가 목적이 되면, 지표는 올라가지만 과학적 목적에는 다가가지 않는 방법들이 나타난다. 벤치마크를 유지하는 사람은 주기적으로 "이 벤치마크의 상위 방법이 실제 과학 문제에서도 나은가"를 확인하고, 필요하면 새 버전을 낸다.

재현 패키지

왜 필요한가. 23.12장에서 재현 패키지의 구조를 정했다. README, 라이선스, 인용 정보, 환경 정의, 데이터 안내, 표·그림별 설정과 실행 스크립트, 기대 결과다. 그러나 구조를 갖춘 것과 실제로 재현되는 것은 다르다. 만든 사람의 컴퓨터에는 설치되어 있는 패키지, 홈 디렉터리의 캐시, 환경 변수, 손으로 한 번 실행한 전처리가 숨어 있다. 이것들은 다른 환경에서 처음부터 실행해 보기 전에는 드러나지 않는다.

구성 요소. 재현 패키지는 네 가지를 묶는다.

깨끗한 환경에서의 점검. 공개 전에 패키지를 새 환경에서 처음부터 실행한다. 새 컨테이너나 새 가상 머신이 가장 좋고, 최소한 새 사용자 계정과 새 clone에서 한다.

# 집필 시점 예시: 새 clone에서 README의 명령만으로 실행해 본다
git clone --branch v1.0.0 <재현 패키지 저장소 주소> /tmp/repro-check
cd /tmp/repro-check
# README의 "설치" 절 명령을 그대로 복사해 실행한다
# README의 "smoke test" 명령을 실행한다 (작은 설정, 수 분 이내)
# README의 대응표에서 표 하나를 골라 명령을 실행하고 기대 결과의 범위와 비교한다

이때 README에 없는 명령을 하나라도 쳤다면, 그 명령이 README의 빈칸이다. 가장 강한 점검은 다른 사람에게 README만 주고 표 하나를 재현해 달라고 하는 것이다(23.12장 실습). 그 사람이 물어본 질문이 문서의 빈칸이다.

작은 설정의 smoke test. 전체 재현에 몇 시간이 걸린다면, 같은 코드 경로를 작은 데이터와 짧은 학습으로 몇 분 안에 통과하는 smoke test를 따로 둔다. 독자는 전체 실행 전에 환경이 맞는지 확인할 수 있고, 유지보수하는 사람은 CI에서 이 테스트로 패키지가 썩지 않았는지 확인할 수 있다(6.6장). 데이터를 공개할 수 없는 경우에도 같은 스키마의 합성 데이터로 smoke test를 돌리면 파이프라인 전체가 동작함을 보일 수 있다.

기대 결과와 허용 범위. "표 2의 숫자를 얻는다"가 아니라 "seed 5개 평균 ± 표준편차가 results/expected/table2.csv의 범위 안"처럼 판정할 수 있게 쓴다. GPU 연산의 비결정성과 라이브러리 버전에 따라 숫자가 조금씩 다를 수 있으므로(22.2장), 허용 범위가 없으면 재현을 시도한 사람은 작은 차이가 정상인지 판단할 수 없다. 재현 가능한 계산 연구의 규칙들(Sandve 외, 2013)과 ML 학회의 재현성 체크리스트(Pineau 외, 2021)가 점검 항목을 고르는 데 참고가 된다.

이 로드맵에 기여하기

왜 필요한가. 이 책도 오픈소스다. 독자가 읽다가 발견한 오류, 직접 겪은 실패, 더 나은 퀴즈 문항이 다음 독자의 학습을 바꾼다. 그리고 이 저장소에 기여하는 과정 자체가 이 장에서 다룬 기여 흐름(이슈 → branch → 검사 → PR → 리뷰)의 연습이다. 아래 내용은 저장소의 CONTRIBUTING.md와 editorial/workflow.md를 따른다. 규칙이 바뀌었을 수 있으니 기여하기 전에 두 파일을 직접 읽는다.

기여할 수 있는 것.

절차. 한 작업은 한 이슈, 한 branch, 한 PR이다.

1. 이슈. 새 장·새 부·트랙 변경 같은 큰 변경은 먼저 이슈로 제안한다. 저장소에는 "장 집필", "내용 오류", "새 분야 제안", "플랫폼 작업" 이슈 양식이 있다. 내용 오류 양식은 위치, 무엇이 틀렸는지, 근거(올바른 내용과 출처 또는 재현 방법)를 묻는다.

2. branch. <종류>/<짧은-설명> 형식으로 만든다. 원고는 write/, 오탈자·사실 오류·링크 수정은 fix/다(예: fix/battery-unit-typo).

3. 변경과 검사. 변경 후 저장소 루트에서 검사를 통과시킨다. 목차 구조를 바꿨다면 목차를 다시 생성한다. OUTLINE.md는 생성 파일이므로 직접 고치지 않는다.

   python3 scripts/book.py check
   python3 scripts/book.py outline   # 목차 구조를 바꾼 경우에만
   

4. PR. PR 템플릿이 "무엇을, 왜", 종류, 검증 체크리스트(검사 통과, 코드 출력은 실제 실행 결과, 퀴즈 정답을 직접 확인, 새 인용은 원문을 확인하고 data/references.bib에 추가, 장 status는 draft까지만), 확인 필요 목록(직접 확인하지 못한 사실·수치·인용)을 묻는다. 한 PR에는 한 주제만 담는다.

5. 리뷰와 status. 장의 status는 outline → draft → review → done으로 올라간다. 기여자(AI 에이전트 포함)는 draft까지만 올리고, review와 done은 사람 리뷰어가 올린다.

지켜야 할 것.

• 기여한 내용은 저장소와 같은 라이선스로 공개된다. 코드는 MIT, 본문·퀴즈·그림·데이터는 CC BY 4.0이다(LICENSE, LICENSE-CONTENT).
• 확인하지 않은 논문·API·수치를 쓰지 않는다. 퀴즈 정답과 실습 결과는 직접 검증한 것만 쓴다.
• 장 id, 퀴즈 문항 id, 위젯 name은 학습자의 진도 기록 키이므로 바꾸지 않는다. 퀴즈 문항의 내용을 크게 바꾸면 기존 id를 고치지 말고 새 id로 쓴다.
• 데이터와 그림은 라이선스를 확인한 것만 넣고 출처를 밝힌다.

실패 사례 기여의 예. 실패 사례는 이 책에서 가장 기여하기 좋은 부분이다. 독자마다 다른 실패를 겪고, 실패 사례는 겪어 본 사람만 정확하게 쓸 수 있다. 장의 기존 항목과 같은 형식(굵은 글씨의 한 줄 요약, 무슨 일이 일어나는지, 어떻게 피하는지)으로 쓴다.

- **물리량의 단위를 데이터 카드에 쓰지 않는 것.** 온도 열이 섭씨인데 단위가 적혀
  있지 않으면, 받은 사람이 켈빈으로 가정해 전처리할 수 있다. 모델은 아무 오류 없이
  학습되지만 영하의 측정값이 음의 절대온도가 되고, 온도에 의존하는 물리 항이 엉뚱한
  값을 낸다. 데이터 카드의 구성 항목에 열마다 단위를 쓰고, 로더에서 값의 범위를 검사한다.

PR 설명에는 이 실패를 언제 어떻게 겪었는지, 또는 재현하는 방법을 적는다. 리뷰어가 실패 사례의 사실 여부를 판단할 근거가 된다.

참고 문헌

• Wilkinson, M. D., et al. (2016). The FAIR guiding principles for scientific data management and stewardship. Scientific Data, 3, 160018. — 데이터 공개의 FAIR 원칙
• Gebru, T., et al. (2021). Datasheets for datasets. Communications of the ACM, 64(12), 86–92. — 데이터셋 문서화 질문 목록
• Koh, P. W., et al. (2021). WILDS: A benchmark of in-the-wild distribution shifts. In Proceedings of the 38th International Conference on Machine Learning, PMLR 139, 5637–5664. — 실제 분포 이동을 담은 벤치마크 설계
• Kapoor, S., & Narayanan, A. (2023). Leakage and the reproducibility crisis in machine-learning-based science. Patterns, 4(9), 100804. — 과학 분야 ML의 누수 유형
• Sandve, G. K., Nekrutenko, A., Taylor, J., & Hovig, E. (2013). Ten simple rules for reproducible computational research. PLoS Computational Biology, 9(10), e1003285.
• Pineau, J., et al. (2021). Improving reproducibility in machine learning research (A report from the NeurIPS 2019 reproducibility program). Journal of Machine Learning Research, 22(164), 1–20.