이번 시간에는 깃허브 문서 템플릿을 직접 실습해보고, 실제 오픈 소스 프로젝트인 모던 자바스크립트 튜토리얼에 기여하는 전 과정을 진행했습니다.
1. 깃허브 문서 템플릿이란?
깃허브에서는 프로젝트 운영에 필요한 다양한 문서 템플릿을 제공합니다. 이슈나 PR을 생성할 때 매번 같은 형식으로 작성할 수 있도록 미리 틀을 만들어두는 기능입니다.
문서 템플릿을 사용하면 좋은 이유는 다음과 같습니다.
- 이슈와 PR의 작성 형식을 통일하여 프로젝트 관리가 수월해집니다.
- 기여자가 무엇을 작성해야 할지 명확히 알 수 있어 커뮤니케이션 비용이 줄어듭니다.
- 버그 리포트, 기능 요청 등 유형별로 다른 템플릿을 설정해 효율적으로 운영할 수 있습니다.
2. 깃허브 문서 템플릿 실습
이슈 템플릿 만들기
레포지토리의 .github 폴더 하위에 ISSUE_TEMPLATE 폴더를 생성하고 템플릿 파일을 추가합니다.
.github/
└── ISSUE_TEMPLATE/
├── bug_report.md # 버그 리포트 템플릿
└── feature_request.md # 기능 요청 템플릿각 파일의 상단에 프론트매터(Front Matter) 를 작성하면 이슈 생성 시 자동으로 레이블과 제목이 설정됩니다.
---
name: 버그 리포트
about: 버그를 제보해 주세요
title: "[BUG] "
labels: bug
assignees: ''
---
## 버그 설명
버그에 대해 명확하게 설명해 주세요.
## 재현 방법
1. ...
2. ...
## 예상 동작
어떻게 동작해야 하는지 설명해 주세요.
## 실제 동작
실제로 어떻게 동작하는지 설명해 주세요.PR 템플릿 만들기
.github 폴더에 PULL_REQUEST_TEMPLATE.md 파일을 추가하면 PR 생성 시 자동으로 템플릿이 적용됩니다.
## 변경 사항
이 PR에서 변경된 내용을 설명해 주세요.
## 관련 이슈
closes #이슈번호
## 체크리스트
- [ ] 코드 스타일 가이드를 준수했습니다.
- [ ] 테스트를 추가했습니다.
- [ ] 관련 문서를 업데이트했습니다.3. 깃허브 문서 템플릿 실습 2
이슈 템플릿과 PR 템플릿을 모두 설정한 뒤 실제로 이슈를 생성하고 PR을 제출해보는 실습을 진행했습니다.
직접 해보니 템플릿이 있을 때와 없을 때의 차이가 크게 느껴졌습니다. 템플릿이 있으면 작성자도 빠짐없이 정보를 채울 수 있고, 검토자 입장에서도 내용 파악이 훨씬 수월합니다. 오픈 소스를 처음 운영하거나 팀 프로젝트를 시작할 때 가장 먼저 세팅해두면 좋은 기능이라는 것을 실감했습니다.
4. 모던 자바스크립트 튜토리얼이란?
모던 자바스크립트 튜토리얼(javascript.info) 은 자바스크립트의 기초부터 심화까지 체계적으로 다루는 오픈 소스 문서 프로젝트입니다.
영어 원문을 다양한 언어로 번역하는 작업이 깃허브를 통해 오픈 소스 방식으로 진행되고 있으며, 한국어 번역 레포지토리도 별도로 운영되고 있습니다. 이번 실습에서는 이 프로젝트에 직접 기여하는 전 과정을 경험했습니다.
5. 모던 자바스크립트 튜토리얼 기여 실습 — 가이드라인 살펴보기
본격적인 기여에 앞서 프로젝트의 기여 가이드라인(CONTRIBUTING.md) 을 꼼꼼히 읽는 것이 중요합니다.
확인해야 할 주요 항목들입니다.
- 번역 규칙 — 특정 용어를 어떻게 번역해야 하는지 지침이 있는지 확인합니다.
- 코드 스타일 — 커밋 메시지 형식이나 파일 작성 규칙을 확인합니다.
- 이슈 확인 — 내가 기여하려는 내용이 이미 다른 사람이 진행 중인지 이슈 탭에서 먼저 확인합니다.
- PR 규칙 — PR 제목 형식, 브랜치 명명 규칙 등을 확인합니다.
가이드라인을 먼저 파악하지 않고 무작정 PR을 올리면 반려될 수 있기 때문에, 이 단계는 건너뛰지 않는 것이 중요합니다.
6. 모던 자바스크립트 튜토리얼 기여 실습 — 로컬 환경 셋팅
가이드라인 확인이 끝나면 본격적인 작업 전 로컬 환경을 준비합니다.
# 1. 원본 레포지토리를 내 계정으로 Fork합니다
# 2. Fork한 레포지토리를 로컬로 Clone합니다
git clone https://github.com/내계정/ko.javascript.info.git
# 3. 원본 레포지토리를 upstream으로 추가합니다
git remote add upstream https://github.com/javascript-tutorial/ko.javascript.info.git
# 4. 작업할 브랜치를 생성합니다
git checkout -b fix/오타-수정원본 레포지토리를 upstream 으로 등록해두면, 이후 원본에 업데이트가 생겼을 때 내 Fork에도 최신 변경 사항을 쉽게 반영할 수 있습니다.
7. 모던 자바스크립트 튜토리얼 기여 실습 — PR 보내기
작업이 완료되면 변경 사항을 커밋하고 내 Fork에 Push한 뒤 원본 레포지토리에 Pull Request 를 생성합니다.
# 변경 사항 스테이징 및 커밋
git add .
git commit -m "fix: 오타 수정 (변수 → 변수명)"
# Fork한 내 레포지토리로 Push
git push origin fix/오타-수정PR을 생성할 때는 프로젝트의 PR 템플릿에 맞게 작성합니다.
- 어떤 내용을 수정했는지 명확히 설명합니다.
- 관련 이슈 번호가 있다면 함께 연결합니다.
- 가이드라인에서 요구하는 체크리스트를 모두 확인합니다.
PR이 제출되면 프로젝트 메인테이너 또는 커미터가 코드 리뷰를 진행합니다. 요청된 수정 사항이 있으면 반영한 뒤 다시 Push하면 PR에 자동으로 업데이트됩니다. 최종 승인을 받으면 원본 레포지토리에 Merge되어 공식 기여자가 됩니다.
