서론 - 선정 계기 및 add_docs가 무엇인가?
이번 OSSCA를 진행하면서 팀 프로젝트 외에도, 나만의 방식으로 오픈소스에 직접 기여하고 싶은 마음이 강하게 들었다. 단순히 주어진 이슈를 해결하는 것이 아니라, 실사용자의 관점에서 실질적인 가치를 더할 수 있는 부분을 주체적으로 발굴해보고 싶었다.
그 과정에서 내가 주목하게 된 기능은 바로 /add_docs 명령어였다.
add_docs 명령어란?
/add_docs 는 PR에서 변경된 코드 내 함수나 클래스 등 코드 컴포넌트에 대해 자동으로 문서(docstring) 를 생성해주는 명령어다.
예를 들어 PR에서,
/add docs혹은 특정 함수에 적용하고 싶을 때,
/add_docs my_function다음과 같은 형태로 자동으로 docstring이 제안된다:
이는 팀 단위 협업에서 코드 가독성과 문서화의 품질을 높이는 데 매우 유용한 기능이다. 그런데 문제는, 이 기능이 매번 수동으로 명령어를 입력해야만 동작한다는 점이었다.
본문 - 문제 파악과 해결 과정
처음 내가 파악했을 때는 "왜 이렇게 좋은 기능이 자동화가 안되어있을까?" 라는 물음부터 시작하였다.
실제로 다음과 같이 자동화 명령어는 이 3개인데, 이 3개 명령어만큼이나 중요한 /add_docs도 중요하다고 생각하는데 왜 이 명령어는 여기에 포함되어있지 않은지 궁금하였다.
그래서 다음 이슈를 기반으로 기능 개선을 제안하게 되었다.
관련 issue
Support auto‐run of add_docs on PR open #1768
처음엔 이 기능이 내부적으로 자동 실행되지 않는다고 판단하고,
configuration.toml 혹은 .pr_agent.yaml에 대한 설정 추가
event_handler.py에서 PR 생성 이벤트 후 /add_docs를 직접 실행
…하는 방식의 코드를 제안하는 PR을 작성했다.
하지만 리뷰를 통해 알게된 사실은, 이미 기존의 pr_commands 설정에 /add_docs를 포함시키기만 해도 자동으로 실행된다는 것이었다.
즉, 기능은 이미 구현되어 있었고, 다만 명확한 문서화가 되어 있지 않아 사용자가 인지하기 어려운 상태였던 것이다.
따라서 다음과 같이 문서화 작업과 테스트 커버리지를 작업하겠다고 말씀 드렸고,
흔쾌히 수락해주셔서 기여를 시작하게 되었다.
초기 PR - 기능 자동화 PR 제출 -> 방향 전환
docs: add /add_docs to pr_commands for auto execution #1794
처음에는 /add_docs 명령어가 자동으로 실행되지 않는다고 판단하여,
자동화를 위한 기능 추가 PR을 제출했다.
해당 PR에서는 configuration.toml의 기본 설정에 /add_docs를 포함시켜,
PR이 열릴 때 자동으로 문서화를 실행하도록 설정했다.
하지만 메인 컨트리뷰터분의 피드백에 따르면,
/add_docs는 기본 자동 실행 대상이 아니며, 사용자가 원할 경우 pr_commands에 직접 명시해서 사용할 수 있어야 한다는 것이었다!
이에 따라 나는 기능 추가보다는
으로 기여 방향을 전환하게 되었고, 다음 PR을 통해 공식 문서 내 사용법을 정리하게 되었다.
실제 작성한 PR
docs: document how to auto-trigger /add_docs via pr_commands #1795
해당 PR에서는 documentation.md에 /add_docs의 자동 실행 방법을 명확히 문서화했다.
작성 시 주안점은 다음과 같다:
기존 review.md, improve.md와 동일한 문서 구조와 문장 톤을 유지하고,
특정 설정 파일 이름 (configuration.toml, .pr_agent.yaml)은 직접 언급하지 않고, 링크와 함께 "configuration file"로 통일하며,
GitHub App을 사용할 때만 해당 설정이 적용된다는 점을 명확하게 서술하였다!
처음에는 간단한 문서화 작업이라 생각했지만, 리뷰어의 피드백을 반영하며 내용을 보완했고, 그 결과 만족스럽게 merge될 수 있었다
결론
이번 문서화 PR은 단순히 글을 추가하는 것에서 더 나아가,
실제 사용자가 놓치기 쉬운 설정 방법을 명확히 설명하는 데 의미가 있었다.
처음에는 간단한 문서화 작업이라 빠르게 끝날 거라 생각했지만,
리뷰어의 피드백을 반영하며 내용의 깊이와 정확성을 높일 수 있었고,
최종적으로는 PR-Agent의 공식 문서에 내 설명이 반영되었다는 점에서 매우 큰 보람을 느꼈다!
그리고 많은 사람들이 사용 중인 PR-Agent 프로젝트에 내 글이 일부로 남게 되었다는 사실이 개인적으로도 큰 동기부여가 되었고, 이제 문서화와 다른 부분에서도 기여도 해보고 싶다는 생각이 들었다.앞으로도 오픈소스에 지속적으로 기여하고 싶다!
이제 나는 테스트 코드 PR을 작성하러 갈 예정이다! 😎
