좋은 오픈소스 PR이란? (내 PR이 닫힌 경험에서 얻은 교훈)

Source: Dev.to

The Bug

ClawHub의 검색 순위 시스템을 파고들던 중 (ClawHub는 OpenClaw의 스킬 마켓플레이스) 이상한 점을 발견했습니다: 스킬을 정확한 슬러그로 검색하면 반드시 상단에 표시되는 것이 아니라, 경우에 따라 전혀 표시되지 않기도 했습니다.

원인은 검색 파이프라인에 있었습니다. 벡터 유사도 검색이 먼저 실행되고, 그 뒤에 어휘적 부스트가 적용되었습니다. 하지만 스킬의 다운로드 수가 적고 해당 스킬 이름에 대한 임베딩 점수가 낮으면, 벡터 리콜 단계에서 해당 스킬이 아예 제외되었습니다. 정확한 슬러그 매치는 +1.4 부스트를 받지 못했으며, 후보 풀에 들어가지 않았습니다.

My PR: The Quick Fix

벡터 검색 후 슬러그를 O(1) 조회하는 슬러그 리콜 단계를 추가하고, 누락된 경우 삽입했습니다. 간단했고 잘 동작했습니다.

What went wrong

• V1은 너무 하드코딩돼 있었습니다. 리뷰 단계에서 바로 지적되었습니다.
• V2는 중요한 엣지 케이스를 놓쳤습니다: 사용자가 다운로드 수로 정렬을 의도적으로 선택했다면 어떻게 할까요? 내 삽입 로직이 그들의 명시적 선택을 무시하게 됩니다.

The Competing PR

다른 기여자가 제출한 수정이 대신 머지되었습니다. 주요 차이점은 다음과 같습니다:

• 사용자 선택 존중 – 시스템 기본값과 사용자가 선택한 정렬을 구분하여 명시적인 사용자 결정을 보존했습니다.
• 근본 원인 해결 – 하위 단계에서 패치하는 대신 문제 코드를 상위에서 제거했습니다.
• 데모 영상 – 전후 화면 녹화를 짧게 제공해 유지보수자가 변경 사항을 빠르게 검증할 수 있게 했습니다.
• 회귀 테스트 – 내가 고려하지 못한 엣지 케이스를 다루는 테스트를 추가했습니다.

What I Learned

1. Edge case를 먼저 생각하라

행동이 바뀔 때마다 최소 세 가지 시나리오를 적어 보세요. 하나도 떠오르지 않으면 충분히 고민하지 않은 것입니다.

2. 증상이 아니라 근본 원인을 고쳐라

스스로에게 물어보세요: 다른 깨진 코드를 보완하기 위해 코드를 추가하고 있나요? 그렇다면 근본적인 실수를 고쳐야 합니다.

3. 작업 과정을 보여라

스크린샷, 영상, 전후 비교 등을 포함하세요. 많은 PR을 검토하는 유지보수자는 검증이 쉬운 기여에 더 끌립니다.

4. 전체 시스템을 이해하라

변경하는 코드만 안다고 해도 부족합니다. 주변 코드와 그 상호작용을 파악해야 합니다.

If You’re New to Open Source

• 기존 PR을 먼저 읽어보고 자신의 PR을 제출하세요.
• 서두르지 마세요 — 가장 좋은 해결책이 승리합니다, 가장 먼저 만든 것이 아니라.
• 리뷰 코멘트에 빠르고 신중하게 답변하세요.
• PR이 닫히는 것도 괜찮습니다; 하나의 닫힌 PR이 열 개의 머지된 오타 수정보다 더 많은 것을 가르쳐 줄 수 있습니다.

이 글은 ClawHub 검색 순위 PR 작업 경험을 바탕으로 작성되었습니다. 경쟁 PR이 객관적으로 더 나았으며, 배울 수 있는 기회를 제공해 준 것에 감사드립니다.