초보자를 위한 GitHub에서 개발 프로젝트 협업 시작하기: Fork·Clone·Pull Request를 한 번에 이해하는 실습 가이드

1) 전체 그림: Fork, Clone, PR이 필요한 이유

• Fork: 다른 사람(또는 조직)의 저장소를 내 계정으로 복제해 “내 공간”에서 마음껏 실험할 수 있게 합니다. 원본에 직접 쓰기 권한이 없어도 기여 가능.
• Clone: Fork한 저장소를 내 PC로 내려받는 것. 로컬에서 코드 수정·실행·테스트를 합니다.
• Pull Request(PR): 내가 만든 변경사항을 원본 저장소에 “이 변경을 합쳐주세요”라고 제안하는 협업 절차. 코드 리뷰와 품질 관리의 핵심입니다. 한 문장으로 요약하면: Fork로 내 리포지토리를 만들고, Clone으로 PC에서 작업한 뒤, PR로 원본에 반영을 요청합니다.

2) 실습 준비: 꼭 알아야 할 용어 3개

(1) origin과 upstream

• origin: 보통 내 Fork 저장소를 가리키는 원격 이름
• upstream: 보통 원본 저장소를 가리키는 원격 이름(직접 추가해줘야 하는 경우 많음)

(2) main과 브랜치

협업에서는 main(또는 master)에 바로 작업하지 않고, 작업용 브랜치를 만들어 변경합니다. 충돌을 줄이고 리뷰가 쉬워져요.

(3) 커밋(Commit)

작업을 “한 덩어리”로 저장하는 기록. 메시지는 나중에 찾기 쉽게 무엇을 왜 바꿨는지 쓰는 게 중요합니다.

3) 실습: Fork → Clone → 브랜치 → PR까지 한 번에

아래 예시는 “문서 오타 수정” 같은 작은 기여를 가정합니다. 개발 초보자가 가장 많이 성공하는 첫 PR이기도 해요.

Step 1. Fork 하기 (웹에서)

원본 저장소 페이지에서 Fork 버튼을 눌러 내 계정으로 복제합니다. 이제 내 리포지토리가 생겼습니다.

Step 2. Clone 하기 (터미널에서)

내 Fork 저장소를 로컬로 받습니다.

git clone <내-포크-저장소-주소>
cd <저장소-폴더>

Step 3. upstream 추가(선택이지만 강력 추천)

원본 저장소 변경사항을 따라가려면 upstream을 잡아두면 편합니다.

git remote add upstream <원본-저장소-주소>
git remote -v

Step 4. 최신 상태로 동기화하고 브랜치 만들기

원본이 업데이트됐을 수 있으니 먼저 맞춘 뒤 작업 브랜치를 만듭니다.

git fetch upstream
git checkout main
git merge upstream/main
git checkout -b docs/fix-typo

브랜치 이름은 팀 규칙이 있으면 따르고, 없으면 feature/, fix/, docs/ 같은 접두사를 붙이면 관리가 쉬워요.

Step 5. 코드 수정 → 커밋

예를 들어 README.md의 오타를 수정했다고 해볼게요.

git status
git add README.md
git commit -m "docs: fix typo in README"

커밋 메시지는 동사로 시작하고, 변경 목적이 보이게 적으면 리뷰어가 이해하기 좋습니다.

Step 6. 내 Fork(origin)로 push

로컬 브랜치를 내 원격 저장소에 올립니다.

git push origin docs/fix-typo

Step 7. Pull Request 만들기 (웹에서)

내 Fork 저장소로 가면 “Compare & pull request” 같은 버튼이 보입니다. PR 작성 시 아래 3가지를 채우면 통과율이 확 올라가요.

• 무엇을 바꿨는지: 오타 수정, 문구 개선 등 한 줄 요약

• 왜 바꿨는지: 혼동 방지, 문서 정확성 개선 등 이유

• 어떻게 확인했는지: 문서 렌더링 확인, 빌드/테스트 여부 예시 템플릿:

• 변경 내용: README 설치 문서 오타 1건 수정

• 확인: 로컬에서 문서 확인(렌더링 문제 없음)

4) 협업에서 자주 겪는 상황 3가지와 해결

(1) PR에서 “충돌(Conflict)”이 났어요

원본에서 같은 파일이 바뀌었을 가능성이 큽니다. 로컬에서 원본 변경을 다시 가져와 정리합니다.

git fetch upstream
git checkout main
git merge upstream/main
git checkout docs/fix-typo
git merge main

충돌 파일을 열어 수동으로 정리한 뒤 다시 커밋하고 git push 하면 PR에 반영됩니다.

(2) 리뷰에서 수정 요청이 왔어요

PR 닫지 말고 같은 브랜치에서 수정 커밋을 추가하면 됩니다.

# 수정 후
git add .
git commit -m "docs: refine wording per review"
git push origin docs/fix-typo

(3) 실수로 다른 파일까지 커밋했어요

작은 실수는 흔합니다. 불필요한 변경은 되돌리고 다시 커밋하세요.

git restore <파일명>
git add <파일명>
git commit -m "chore: revert unintended changes"

5) 초보자가 첫 협업에서 성공하는 팁

• 작게 바꾸고 자주 PR: 큰 기능보다 작은 개선이 합쳐질 확률이 높습니다.
• 한 PR = 한 목적: 문서 수정 PR에 코드 리팩터링을 섞지 않기.
• 질문은 구체적으로: “안 돼요”보다 “어느 명령에서 어떤 메시지가 나왔는지”를 공유하면 해결이 빨라요. 여기까지 따라왔다면, 이제 GitHub 협업의 뼈대는 잡힌 겁니다. 다음 단계로는 팀의 브랜치 전략(예: Git Flow 간단 버전)이나 리뷰 규칙을 익히면, 개발 프로젝트에서 훨씬 자연스럽게 기여할 수 있어요.