본문으로 건너뛰기

작은 오픈소스 유지보수 1년 회고

별 수백 개짜리 작은 라이브러리를 1년간 유지보수하며 배운 이슈 트리아지, 릴리스 리듬, 번아웃 방지에 대한 회고입니다.

· 3분 읽기

작은 오픈소스 유지보수 1년 회고

개요

작년에 회사에서 쓰려고 만든 유틸리티 라이브러리를 공개했는데, 사용자가 조금씩 붙으면서 어느새 이슈 트래커가 제 삶의 일부가 됐습니다. 스타 수로 치면 아주 작은 프로젝트지만, 1년을 지내며 “코드 잘 짜기”와는 전혀 다른 종류의 일을 배웠습니다. 이 글은 작은 오픈소스를 유지보수하는 사람의 1년을 정리한 회고입니다.

이슈 트리아지: 유지보수의 80%

솔직히 코드를 쓰는 시간보다 이슈를 읽고 답하는 시간이 훨씬 길었습니다. 처음엔 모든 이슈에 즉시 답하려고 애썼는데 금방 지쳤고, 지금은 트리아지를 정해진 리듬으로 합니다. 주 한 번 이슈함을 열고, 각 이슈를 네 부류로 나눕니다.

  • 버그 + 재현 가능: 최우선. 재현 스크립트가 있으면 그날 안에 고칩니다.
  • 버그처럼 보이는 사용법 질문: 재현이 안 되면 대부분 이 부류입니다. 답변 후 템플릿에 “재현 코드를 붙여주세요”를 강제하는 걸로 왕복을 줄였습니다.
  • 기능 요청: 방향성과 맞는지만 보고 라벨만 붙입니다. 당장 만들지 않습니다.
  • 범위 밖: 정중히 닫습니다. 닫는 것이 잔인해 보였지만, 열어두면 양쪽 다 기대만 쌓인다는 걸 배웠습니다.

이슈 템플릿 하나 바꿨을 때 노이즈 비율이 눈에 띄게 줄었습니다. 버그 리포트에 기대했던 필드(버전, 환경, 최소 재현 코드)를 처음부터 받아내는 것이 왕복을 줄이는 가장 싼 투자였습니다.

한 줄 PR의 가치

1년간 받은 PR의 절반쯤은 한두 줄짜리 수정이었습니다. 타입 정의 오타, 문서의 잘못된 예시, 의존성 경고 수정 같은 것들인데, 이런 PR이 쌓인 커밋 히스토리가 제일 고맙습니다. 그래서 저도 다른 프로젝트에 갈 때 사소한 수정을 참지 않고 PR을 엽니다.

한 줄 PR을 대할 때 지키는 규칙을 만들었습니다.

  • 24시간 안에 첫 반응(리뷰든 “이번 주에 볼게요”든)을 준다. 기여자의 열기는 식기 전에 답하는 게 예의라고 봅니다.
  • 완벽을 요구하지 않는다. 컨벤션 안 맞는 한 줄은 제가 머지하면서 고칩니다. 리뷰로 되돌리는 비용이 더 큽니다.
  • 감사를 구체적으로 표현한다. “수정해줘서 고맙다”보다 “덕분에 문서 이슈 세 개가 한 번에 닫혔습니다”가 기여를 계속하게 만듭니다.

다만 한 줄이라도 테스트가 필요한 변경이면 스스로 테스트를 붙입니다. “작으니까 괜찮아”로 넘긴 타입 수정이 하위 호환을 깨뜨린 적이 있었습니다.

릴리스 리듬: 달력이 이끄는 배포

초반에는 수정이 쌓일 때마다 아무 때나 릴리스했는데, 버전이 뭐가 다른지 설명하기 어려워졌습니다. 지금은 시맨틱 버저닝과 고정된 리듬을 지킵니다.

  • 패치·마이너는 쌓인 변경이 있으면 격주 화요일에 릴리스.
  • 브레이킹 체인지는 최소 3개월 전 deprecation 경고를 한 번 넣고 진행.
  • 모든 릴리스는 CHANGELOG와 태그로 남깁니다.
{
  "scripts": {
    "release": "npm test && changeset version && npm publish",
    "check-deprecated": "node scripts/check-deprecations.js"
  }
}

릴리스 자동화(Changesets 같은 도구)를 붙인 뒤로 “릴리스하는 비용”이 거의 0이 됐고, 그러니 자주 하게 됐습니다. 작게 자주 내는 것이 사용자와 유지보수자 모두에게 안전합니다.

번아웃 방지: 1인 운영의 현실

가장 힘들었던 건 코드가 아니라 기대에 대한 죄책감이었습니다. 이슈가 쌓여 있고, 답을 기다리는 사람이 있고, 주말을 갈아 넣으면 다 되지만 그러면 못 합니다. 몇 가지 대책을 세웠습니다.

  • 응답 SLA를 스스로 공표: README에 “이슈 응답은 최대 1주일”이라고 적었습니다. 기대치가 명시되니 조급함이 줄었습니다.
  • 유지보수 모드 선언: 바쁜 달에는 이슈에 “당분간 유지보수 모드”라고 공지했습니다. 숨기니까 죄책감만 커졌지 아무 도움이 안 됐습니다.
  • 함께 관리하기: 반복적으로 기여해준 분에게 커밋 권한을 드렸습니다. 1인 운영의 지속 가능성은 결국 사람 수 문제였습니다.

오픈소스 유지보수는 무료 봉사라는 사실을 유지보수자 본인이 제일 자주 잊는 것 같습니다.

성과보다 배움

1년간의 지표를 보면 스타는 그저 그렇게 늘었지만, 배운 건 확실합니다. 다른 사람이 읽는 코드를 쓰는 법(네이밍, 문서화, 예제), 테스트와 CI의 가치, 그리고 소통이 코드보다 어렵다는 것. 그리고 제 라이브러리를 쓰는 사람이 세 계정이라는 걸 알았을 때, 그래도 계속할 가치가 있었냐는 질문에 대한 답은 여전히 “그렇다”입니다. 누군가의 문제를 조금 덜어줬고, 저도 그들의 버그 리포트로 많이 배웠으니까요.

마무리

작은 오픈소스 유지보수 1년의 결론은 이렇습니다. 이슈 트리아지가 개발이고, 한 줄 PR이 가장 큰 자산이고, 릴리스는 리듬이며, 유지보수자의 지속 가능성이 프로젝트의 지속 가능성입니다. 공개 저장소 하나 운영해보고 싶은 분에게 드리는 조언은 “코드를 완벽히 준비하지 말고, 트리아지 리듬부터 준비하라”입니다. 그리 유명하지 않은 프로젝트의 1년도 이렇게 알차니까요.

Related

· 3 min read

에이전트 툴링 9종을 npm에 공개했습니다

에이전트 앱 개발에서 반복해서 부딪히는 관측·검증·회귀·호환성 문제를 도구 9개로 정리해 npm v0.1.0으로 공개했습니다. 각 도구가 무엇을 하는지와 설치, 데모를 정리합니다.

AI 에이전트오픈소스
→