🚀 오픈소스 기여하기: Fork부터 PR까지

오픈소스 프로젝트에 처음으로 기여하면서 겪었던 시행착오와 해결 과정을 상세히 기록해보겠습니다. Git, GitHub, Vim 등 도구들을 다루면서 배운 점들을 공유하겠습니다.

🎯 프로젝트 개요

대상 프로젝트: qodo-ai/pr-agent

• AI 기반 PR 분석 도구
• Issue #1793: clip_tokens 함수의 단위 테스트 및 문서화 개선 요청

팀 작업 환경:

• 원본 repo: qodo-ai/pr-agent
• 팀 fork: group-3-sPRinter/pr-agent
• 개인 fork: TaskerJang/pr-agent

🔄 Fork와 Clone 설정

초기 상황

E:\pr-agent>git remote -v
origin  https://github.com/group-3-sPRinter/pr-agent.git (fetch)
origin  https://github.com/group-3-sPRinter/pr-agent.git (push)

팀 fork에서 작업을 완료한 상태에서, 원본 레포지토리에 개인 기여로 PR을 보내야 하는 상황이었습니다.

Remote 저장소 관리

# 원본 저장소를 upstream으로 추가
git remote add upstream https://github.com/qodo-ai/pr-agent.git

# 개인 fork를 myfork로 추가
git remote add myfork https://github.com/TaskerJang/pr-agent.git

# 확인
git remote -v

😅 커밋 메시지 수정의 험난한 여정

문제 상황

팀 작업 시 한글로 작성한 커밋 메시지들:

cf0e430c docs: clip_tokens 함수 docstring 개선 및 예제 추가
62e82e4e test: clip_tokens 함수 포괄적인 단위 테스트 추가

오픈소스 기여 시에는 영어 커밋 메시지가 필요했습니다.

시도한 방법들

1차 시도: Interactive Rebase

git rebase -i HEAD~2

문제 발생: Vim 스왑 파일 충돌

E325: ATTENTION
Found a swap file by the name "/e/pr-agent/.git/rebase-merge/.git-rebase-todo.swp"

2차 시도: 스왑 파일 정리

# 스왑 파일 삭제
rm /e/pr-agent/.git/rebase-merge/.git-rebase-todo.swp

# 또는 Windows에서
del ".git\rebase-merge\.git-rebase-todo.swp"

🔧 Vim과의 첫 만남 (그리고 고생)

Vim 기본 조작법 학습

모드 전환:

• i: Insert 모드 진입
• Esc 또는 Ctrl+C: Normal 모드로 복귀
• Ctrl+[: Esc 대안

편집 작업:

• pick을 reword로 변경하여 커밋 메시지 수정 설정

저장 및 종료:

• :wq: 저장하고 종료
• :q!: 저장하지 않고 강제 종료

실제 경험한 문제들

1. INSERT 모드에서 빠져나오지 못하는 문제

   • Esc 키가 작동하지 않을 때: Ctrl+C 사용

2. 스왑 파일 충돌

   • 해결책: D (Delete) 옵션 선택

3. 여러 줄 커밋 메시지 입력

   git commit --amend -m "docs: improve clip_tokens function docstring and add examples
   
   - Enhanced function documentation with clearer descriptions
   - Added practical usage examples
   - Improved parameter and return value documentation"

🛠 Git Rebase 트러블슈팅

문제 상황들과 해결책

1. Rebase 진행 중 중단

git status
# On branch feature/clip-tokens-tests-and-docs
# No commands done.
# Next commands to do (2 remaining commands):
#    pick 62e82e4e test: clip_tokens 함수 포괄적인 단위 테스트 추가
#    pick cf0e430c docs: clip_tokens 함수 docstring 개선 및 예제 추가

해결:

# rebase 설정 수정
git rebase --edit-todo

# 또는 완전 중단 후 재시작
git rebase --abort

2. 단계별 커밋 수정 방법

# 최신 커밋부터 개별 수정
git commit --amend -m "새로운 커밋 메시지"

# 그 다음 커밋 수정을 위한 rebase
git rebase -i HEAD~2

✅ 최종 PR 생성

성공적인 결과

git log --oneline
e2586cb6 (HEAD -> feature/clip-tokens-tests-and-docs) docs: improve clip_tokens function docstring and add examples
1bc0d488 test: add comprehensive unit tests for clip_tokens function

PR 과정

1. 개인 GitHub 계정으로 원본 레포지토리 Fork
2. 개인 fork에 푸시

   git push myfork feature/clip-tokens-tests-and-docs

3. GitHub에서 원본 레포지토리로 PR 생성

PR 템플릿 영어 변환

한글로 작성한 PR 설명을 영어로 변환:

## Pull Request Summary
This PR addresses Issue #1793 by adding comprehensive unit tests and improving documentation for the `clip_tokens` function.

## Key Changes
- Added 21 comprehensive unit tests in `tests/unittest/test_clip_tokens.py`
- Completely improved docstring for `clip_tokens` function
- Maintained perfect backward compatibility

💡 배운 점과 팁

Git 관련

1. Remote 저장소 관리의 중요성

   • upstream: 원본 저장소
   • origin: 팀 또는 개인 fork
   • myfork: 개인 기여용 fork

2. 커밋 메시지 수정 방법들

   # 최신 커밋만 수정
   git commit --amend -m "새 메시지"
   
   # 여러 커밋 수정
   git rebase -i HEAD~n

3. Rebase 트러블슈팅

   # 문제 발생 시 중단
   git rebase --abort
   
   # 스왑 파일 정리
   rm -rf .git/rebase-merge

Vim 관련

1. 필수 명령어

   • i: 편집 모드
   • Esc/Ctrl+C: 일반 모드
   • :wq: 저장 후 종료
   • :q!: 강제 종료

2. 스왑 파일 처리

   • D: 스왑 파일 삭제
   • R: 복구
   • Q: 종료

오픈소스 기여 관련

1. 언어 통일: 영어 커밋 메시지와 PR 설명
2. Fork 전략: 개인 계정으로 fork 후 기여
3. 권한 이해: upstream에 직접 푸시 불가, fork를 통한 기여

🎉 마무리

오픈소스 기여를 하면서 Git, Vim, GitHub의 다양한 기능들을 실제로 사용해볼 수 있었습니다.

특히:

• Git rebase를 통한 커밋 히스토리 수정
• Vim의 기본 조작법과 트러블슈팅
• 오픈소스 기여 프로세스의 전체 흐름

을 직접 경험할 수 있어서 매우 값진 시간이었습니다.

🔗 참고 자료

• Git Interactive Rebase 가이드
• Vim Cheat Sheet
• GitHub Fork & Pull Request 가이드