첫 오픈소스 PR이 16분 만에 반박당했습니다

안녕하세요, 가야태자 @talkit 입니다.

오늘 오픈소스 저장소에 첫 PR을 냈습니다.

그리고 16분 만에 반박당했습니다.

저도 macOS 유저라 검증해보았는데요
... 은 정상 빌드됩니다

「제 말이 맞고 그쪽이 잘못 보신 겁니다」라고 쓰고 싶었습니다.

확인해 보니 그분이 맞았습니다.

---

왜 남의 저장소에 PR을 냈나

요즘 한글 문서(HWP)를 PDF와 마크다운으로 바꿔 주는 도구를 만들고 있습니다.

문제가 하나 있습니다. 맥에는 한컴 자동화 API가 없습니다. 윈도우에서는 한컴을 띄워서 시킬 수 있는데, 맥에서는 그 방법이 아예 없습니다.

그래서 오픈소스 라이브러리 하나에 전적으로 기대고 있습니다.

rhwp — 러스트로 만든 한글 문서 라이브러리

https://github.com/edwardkim/rhwp

한글 문서 쓰시는 분이라면 알아 두실 만한 프로젝트라 소개를 좀 하겠습니다.

무엇	HWP·HWPX를 읽고 PDF·이미지로 그려 주는 러스트 라이브러리
라이선스	MIT — 상용에도 쓸 수 있습니다
언어	문서·이슈 템플릿·행동 강령이 전부 한국어입니다
WASM	브라우저에서도 돕니다
활발한가	PR 번호가 5700번대입니다

국산 문서 포맷을 다루는 오픈소스가 이만큼 정돈된 경우가 드뭅니다. 한컴 없이 HWP를 다뤄야 하는 자리라면 지금 이게 사실상 유일한 길입니다.

그리고 외부 기여가 실제로 머지되고 있었습니다. good first issue 라벨도 붙어 있고요.

이만큼 기대면서 받기만 하는 건 오래 못 갑니다.

그래서 무엇을 돌려줄 수 있는지 목록을 만들었습니다. 고르는 기준은 이랬습니다.

• 고장 났다는 게 증명되는 것 — 논쟁의 여지가 없어야 합니다
• 고치는 게 두 줄인 것 — 리뷰어가 1분이면 판단할 수 있어야 합니다
• 부탁이 아니라 주는 것 — 첫 기여에 「이 기능 넣어 주세요」는 아닙니다

그중 1번이 이번 PR이었습니다.

---

빌드가 안 됐습니다

공식 빌드 명령이 제 맥에서 죽었습니다.

chown: invalid group: 'builder:builder'

원인은 짚었습니다. 맥의 기본 그룹 번호가 20인데, 리눅스에서는 그 번호가 이미 다른 이름으로 쓰이고 있습니다. 그래서 그룹을 만드는 명령이 실패하고, 그 실패가 삼켜진 뒤, 없는 그룹에 권한을 주려다 죽습니다.

고치는 것도 간단했습니다. 이름 대신 번호로 지정하면 됩니다.

그리고 고쳐 보니 같은 자리가 두 곳이었습니다. 앞을 고치니 뒤에서 다시 죽었고요. 첫 오류만 보고 넘어갔으면 절반만 고친 PR을 냈을 겁니다.

두 곳 다 고치고, 맥과 리눅스 양쪽에서 확인하고 PR을 냈습니다. 제목은 이렇게 달았습니다.

macOS 에서 이미지 빌드가 실패하는 것

꽤 잘 썼다고 생각했습니다.

---

16분 뒤

관리자가 아니라 그냥 다른 맥 사용자 한 분이 댓글을 다셨습니다.

문서대로 하면 정상 빌드됩니다.
.env.docker 에 임의로 GID=20을 채우신 듯합니다

그 명령을 제 맥에서 그대로 쳐 봤습니다.

정상 빌드됐습니다.

저장소에 설정 예시 파일이 하나 있습니다. 문서는 그걸 복사해서 쓰라고 안내하고요. 열어 봤습니다.

UID=1000
GID=1000

값이 박혀 있었습니다. 문서대로 복사하면 맥에서도 1000번이 들어가고, 그러면 아무 문제가 없습니다.

부끄러운 대목

그러면 저는 무엇을 했나요. 제 빌드 스크립트를 열어 봤습니다.

복사는 했는데, 그 위에 제 값을 덮어쓰고 있었습니다.

docker-compose.yml 도 읽었고, Dockerfile 도 읽었고, README 명령도 읽었습니다. 그런데 그 예시 파일은 「예시」라고 생각하고 넘겼습니다. 값이 박혀 있을 줄 몰랐고요.

더 부끄러운 게 있습니다. 제 스크립트 주석에 이렇게 적혀 있었습니다.

맥에서는 GID 20이 깨지니 피한다

제가 우회하고 있다는 걸 알면서도, 그게 남의 버그라고 생각했습니다.

---

그래도 전부 틀린 건 아니었습니다

인정하는 댓글을 쓰다가 한 가지가 걸렸습니다.

그 예시 파일의 주석이 「호스트 사용자 UID/GID」 라고 설명하고 있습니다. 설명대로 자기 값을 넣으면 맥에서는 정말 죽습니다.

그리고 여기서 하나 더 보였습니다. 맥만의 일이 아닙니다. 시스템이 이미 쓰는 번호면 리눅스에서도 똑같이 죽습니다.

처음 주장   조건은 너무 넓고(모든 맥),  범위는 너무 좁았다(맥만)

좁히면서 동시에 넓어졌습니다. 이런 정정은 처음이었습니다.

처음   macOS 에서 이미지 빌드가 실패하는 것          ← 거짓
고침   이미 쓰이는 GID 를 넘기면 빌드가 실패한다      ← 참

코드는 한 글자도 안 바꿨습니다. 바꾼 건 문장뿐입니다.

---

댓글을 이렇게 썼습니다

네 가지를 지켰습니다.

1. 먼저 인정했습니다. 첫 줄에 뒀습니다.

확인해 주셔서 고맙습니다. 말씀이 맞고, 제 PR 설명이 틀렸습니다.

변명을 앞에 두면 뒤에 쓴 게 다 변명으로 읽힙니다.

2. 재현해서 인정했습니다. 「그럴 수도 있겠네요」가 아니라, 제 기계에서 다시 돌려 보고 적었습니다.

3. 남는 것이 있는지만 물었습니다. 좁힌 조건을 재현 로그와 함께 붙였습니다.

4. 닫아도 된다고 먼저 말했습니다.

그 정도 값어치가 없다고 보시면 닫아 주셔도 됩니다 — 제가 닫아도 되고요.

지금 돌아보면 4번이 제일 중요했던 것 같습니다.

틀린 사람이 자기 PR을 붙들고 있으면, 상대가 「닫습니다」라고 말하는 부담을 집니다. 그 부담을 제가 가져가야 상대가 값어치만 보고 정할 수 있습니다.

---

3시간 3분

시각	누가	무엇
08:49	저	PR을 냈습니다
09:05	다른 맥 사용자	16분 만에 반박
10:19	저	틀렸다고 적고, 좁혔습니다
11:38	관리자	좁힌 범위 확인, 재현 착수
11:52	관리자	머지

중간에 「제 PR 설명이 틀렸습니다」가 들어 있는 3시간입니다.

틀리면 닫힐 줄 알았는데 그렇지 않았습니다. 돌아보면 틀린 것이 코드가 아니라 설명이었기 때문입니다. 설명을 고치니 남았습니다.

관리자 쪽에서 배운 게 더 많습니다

첫째, 재현부터 하셨습니다. 제 말을 믿고 머지한 게 아닙니다. 제가 로그를 붙였는데도 직접 돌려 보셨고요.

한 번 틀린 사람의 두 번째 주장이니 당연합니다. 그런데 그걸 기분 나쁘지 않게 하셨습니다.

둘째, 두 자리를 다시 세셨습니다. 제가 놓쳐서 한 번 다시 고쳤던 그 자리입니다.

셋째, 기록을 코드에서 분리하셨습니다. 이게 제일 인상 깊었습니다.

머지된 것은 파일 하나에 여섯 줄입니다. 딱 그것만요. 그리고 왜 머지했는지는 문서만 담은 별도 PR로 남기셨습니다.

git blame 하는 사람      두 줄만 본다
왜 그랬는지 찾는 사람     따로 본다

저는 이걸 반대로 하고 있었습니다. 커밋 메시지에 다 넣으려고요. 바로 가져왔습니다.

---

남은 것

며칠 사이에 비슷한 걸 두 번 배웠습니다.

「통과했다」는 답이 아니라 질문입니다. 검증 네 개가 초록이었는데 네 개 다 깨져 있던 날이 있었습니다.

그런데 「실패했다」도 답이 아니라 질문입니다. 이번 건이요.

빌드가 정말 깨졌습니다. 그런데 그 조건을 제 스크립트가 만들고 있었습니다.

실패는 통과보다 믿음직해 보입니다. 뭔가 정말로 깨졌으니까요. 그런데 깨진 게 저쪽인지 이쪽인지는 실패 신호에 안 적혀 있습니다.

그래서 제 문서에 절차로 박았습니다.

1. README가 시키는 명령을 글자 그대로 한 번 칩니다. 내 스크립트로 대신하지 않습니다 — 내 스크립트에는 내 사정이 들어 있습니다
2. 거기서도 재현되면 그때가 제보입니다
3. 재현이 안 되면, 내 조건 중 무엇이 달랐는지 찾습니다. 대개 그게 진짜 이야기입니다

하나 더 — .env.example 같은 파일을 열어 봅니다. 거기 뭐가 박혀 있느냐가 「문서대로 한 사람」의 조건입니다.

---

첫 기여라 긴장했는데, 틀린 채로 시작해서 오히려 배운 게 많았습니다.

30분이면 확인할 수 있었던 것을 남에게 확인시킨 셈입니다. 그런데 그 16분이 없었으면 틀린 설명이 그대로 머지됐을 것이고, 그게 더 나빴을 겁니다.

반박해 주신 분과, 확인해서 머지해 주신 관리자분께 고맙습니다.

다음 PR도 준비해 뒀습니다. 이번엔 문서가 시키는 대로 먼저 돌려 보고 내겠습니다.

---

그래서 무엇을 만들고 있느냐면

rhwp에 기대서 kayatext 를 만들었습니다.

https://github.com/kjh0523/kayatext

인공지능을 위한 문서 변환기 — HWP · DOCX · XLSX 를 마크다운으로 바꿉니다.

요즘 사내 문서를 AI에 물려 보려는 분들이 많은데, 한글 문서가 거기서 막힙니다. 표가 깨지거나 순서가 뒤집히거나요. 마크다운으로 제대로 바꿔 주면 그 다음은 쉽습니다.

그리고 하나 더 정한 게 있습니다. 파일을 서버로 안 받습니다. 러스트를 WASM으로 빌드해서 브라우저 안에서 처리합니다. 계약서나 사내 문서를 남의 서버에 올리는 게 늘 걸렸거든요.

조만간 https://kayautils.com 으로 찾아뵙겠습니다 ^^

읽어 주셔서 감사합니다.