오픈 소스 기여 종합 가이드 1건

2026년 7월 14일 · 약 5분

SceneMakerAI 팀

들어가며

SceneMaker 를 만들면서 쓰는 오픈소스에서 문제를 찾아 고쳐 돌려보낸 과정을 정리한 글이다. 어디서 기여 거리를 찾고, 어떤 순서로 올리고, 무엇이 받아들여졌는지를 적었다.

SceneMaker 는 오픈소스 위에서 돈다. 모델을 띄우는 것도, 음성을 받아쓰는 것도, 화면을 나누는 것도 다른 사람이 만든 도구다. 쓰다 보면 고장 난 곳이 보이고, 그것을 고쳐 돌려보내는 일이 기여다.

2026-10-12 기준으로 다른 개발자가 참여한 기여는 24건이다.

형태	건수	내용
Pull Request	11건	그중 9건이 머지됐다
Issue	9건	문제 보고
Discussion	4건	사용 사례 공유와 질문

전체 목록 → 오픈소스 생태계 기여

이 글에서 다루는 내용은 아래와 같다.

기여 거리는 어디서 나오나
기여의 세 가지 형태
올리기까지의 순서
사례 — 문제 보고에서 반영까지
머지된 기여의 공통점
받아들여지지 않은 경우

1. 기여 거리는 어디서 나오나

기여할 곳을 따로 찾아다니지 않는다. 파이프라인이 실제로 쓰는 도구 에서 나온다.

나오는 경로는 두 가지다.
- 쓰다가 막힌 것 — 언어 식별 모델이 오류 없이 뜨는데 첫 판별에서 멈췄다. 원인을 따라가니 라이브러리 쪽 문제였다.
- 코드를 읽다가 본 것 — 동작을 확인하려고 라이브러리 코드를 읽다가, 한쪽에는 있는 옵션이 다른 쪽에는 빠져 있는 것을 발견했다.
직접 쓰는 도구이기 때문에 문제가 실제로 일어나는 조건을 알고 있다. 이것이 재현 예를 만들 때 가장 큰 도움이 된다.

2. 기여의 세 가지 형태

무엇을 알고 있느냐에 따라 형태가 달라진다.

형태	이럴 때 쓴다	예
Pull Request	원인을 알고, 고칠 방법도 안다	10분 넘는 파일의 재생 시간 표시가 깨지는 문제 수정
Issue	문제는 재현되지만, 어떻게 고칠지는 메인테이너가 정해야 한다	일부 영상이 1프레임으로만 읽히는 문제 보고
Discussion	버그가 아니라 사용 사례나 설계 질문이다	영상 장면을 벡터 DB 에 넣는 방식 공유

고칠 방법이 여러 가지이거나 다른 기능에 영향을 주는 경우에는 PR 보다 Issue 가 먼저다.
Issue 로 보고한 뒤 방향이 정해지면 PR 을 잇는다. 4절의 사례가 이 순서다.

3. 올리기까지의 순서

재현이 가장 먼저다. 문제가 실제로 나는 가장 짧은 예를 만들고, 그 출력을 그대로 붙인다.
겹치는지 확인한다. 제목뿐 아니라 본문까지, 열린 것과 닫힌 것을 모두 검색한다. 같은 파일을 고치는 열린 PR 도 본다.
저장소마다 규칙이 다르다. PR 을 어느 브랜치로 보내는지, 변경 기록을 어떤 형식으로 적는지가 저장소마다 정해져 있다.
작게 고친다. 문제 하나에 PR 하나다. 눈에 띄는 다른 문제는 따로 올린다.
테스트를 붙인다. 고치기 전에는 실패하고 고친 뒤에는 통과하는 테스트가 있으면, 리뷰하는 사람이 직접 확인할 수 있다.
올린 뒤가 절반이다. 리뷰에 답하고, 요청받은 수정을 반영하고, 결과를 목록에 기록한다.

4. 사례 — 문제 보고에서 반영까지

방송 음성에서 어떤 언어인지 가려내는 데 SpeechBrain 의 언어 식별 모델을 쓴다.
모델 파일을 정해진 폴더에 직접 내려받도록 설정하면, 모델은 오류 없이 뜨지만 첫 판별에서 멈췄다.

재현 — 파일 하나를 내려받는 짧은 예를 만들었다. 라이브러리가 돌려준 경로에 파일이 없었다.
원인 — 파일은 원래 이름으로 저장되는데, 라이브러리는 다른 이름으로 저장됐다고 보고 그 경로를 돌려주고 있었다. 모델 가중치는 두 이름이 같아 문제가 없었고, 이름이 다른 라벨 파일만 빠졌다.
보고 — 재현 예, 원인이 되는 위치, 확인한 버전을 적어 Issue 로 올렸다.
수정 — 내려받은 파일을 약속한 이름으로 옮기도록 고치고, 같은 상황을 확인하는 테스트 1개를 붙여 PR 로 올렸다.
반영 — 5일 뒤 메인테이너가 승인하고 머지했다.

5. 머지된 기여의 공통점

작다. 아홉 건 가운데 가장 큰 것이 81줄이고, 대부분 30줄 안팎이다. 파일은 한 건을 빼고 3개 이하다.
테스트가 있다. 아홉 건 모두 테스트가 함께 들어갔다.
이미 있는 방식을 따른다. 옵션을 더한 세 건은 새 방식을 만들지 않고, 같은 저장소의 옆 기능이 하는 방식 그대로 맞췄다.
걸리는 시간은 저장소마다 다르다. 올린 당일에 머지된 것도 있고, 석 달 넘게 걸린 것도 있다.

6. 받아들여지지 않은 경우

올린 것이 모두 받아들여지지는 않는다. 닫힌 경우에서 배운 것은 아래와 같다.

경우	배운 것
같은 수정이 이미 다른 PR 로 올라와 있었다	올리기 전 검색을 닫힌 것까지, 본문까지 넓힌다
메인테이너가 같은 문제를 직접 고쳐 반영했다	문제는 해결됐다. 고칠 방법이 분명하지 않으면 Issue 로 먼저 묻는다

AI 도구로 작성한 기여를 받지 않는다고 밝힌 저장소가 있다. 기여 안내와 정책을 먼저 읽고, 그런 곳에는 올리지 않는다.
한 메인테이너에게 하루에 여러 건을 몰아 보내지 않는다. 저장소 여러 개를 한 사람이 관리하는 경우가 많다.
닫힌 건도 목록에서 지우지 않고 경위를 적어 둔다. 같은 실수를 다시 하지 않기 위해서다.

마무리

SceneMaker 를 만들면서 오픈소스에 기여한 과정을 정리했다.

현재 상태를 정리하면 아래와 같다.

다른 개발자가 참여한 기여가 24건이고, 그중 PR 9건이 머지됐다.
기여 거리는 파이프라인이 실제로 쓰는 도구에서 나온다.
재현하고, 겹치는지 확인하고, 작게 고쳐 테스트와 함께 올린다.
머지된 것은 모두 작고, 테스트가 있고, 그 저장소의 방식을 따른 것이다.

기여는 계속 이어 가고 있다. 건별 내용은 아래 목록에서 볼 수 있다.

오픈소스 생태계 기여

참고 링크)

본 글은 과학기술정보통신부·정보통신산업진흥원 「2026년 오픈소스 AI·SW 개발·활용 지원사업」의 지원으로 수행된 연구 결과입니다.

들어가며​

1. 기여 거리는 어디서 나오나​

2. 기여의 세 가지 형태​

3. 올리기까지의 순서​

4. 사례 — 문제 보고에서 반영까지​

5. 머지된 기여의 공통점​

6. 받아들여지지 않은 경우​

마무리​