GitHub 저장소 문서화 표준
학습 목표 매핑
SKALA 3기 Module 7 — 데이터 분석 Mini-project (Learning Objective 7-4)
- Objective: 프로젝트 전체를 GitHub에 버전 관리하고 / README·요구사항(requirements.txt)·실행 지침 명시 / 타인이 리포를 클론 후 5분 내 실행 가능 (Bloom L6-Create)
- Evaluation: 문서 완성도 + 재현성
GitHub 저장소에 필요한 파일
1. README.md (필수)
목적: 사용자가 가장 먼저 보는 파일
최소 섹션:
- 프로젝트 제목
- 설명 (1-2 문단)
- 주요 기능
- 설치 방법
- 사용 예제
- 성과 지표
- 라이선스
2. LICENSE.md
목적: 코드 사용 권한 명시
추천 옵션:
- MIT License: 가장 관대함 (상업 사용 가능)
- Apache 2.0: 특허 보호 포함
- GPL: 2차 저작물도 오픈소스 필수
3. CONTRIBUTING.md
목적: 외부 기여자 가이드
포함 내용:
- 이슈 보고 방법
- 개발 환경 설정
- 코드 스타일 가이드
- 테스트 요구사항
- Pull Request 프로세스
4. .gitignore
목적: Git이 추적하지 않을 파일 지정
Python/ML 프로젝트 예시:
# 바이트 컴파일 파일
__pycache__/
*.py[cod]
*$py.class
# 가상환경
venv/
env/
# IDE
.vscode/
.idea/
# 데이터 (큰 파일)
data/raw/
*.csv
*.xlsx
*.parquet
# 모델
models/
*.pkl
*.h5
# OS
.DS_Store
.env
README.md 효과적인 구조
연구 기반 성공 요소
분석 대상: 9,000+ GitHub README 파일
성공과 상관 있는 요소:
- ✅ 명확한 헤더 (H1, H2, H3)
- ✅ 잘 작성된 문단 설명
- ✅ 코드 예제
- ✅ 시각적 요소 (다이어그램, 이미지)
상관 없는 요소:
- ❌ README 길이 자체
- ❌ 코드 스니펫 개수
- ❌ 이미지 개수
결론: 명확한 제목과 실질적인 설명 콘텐츠가 가장 중요
권장 README 섹션 순서
1. 프로젝트 제목 및 설명
# 붓꽃 분류 머신러닝 프로젝트
이 프로젝트는 물리적 특성(꽃받침 길이·너비 등)을 기반으로 붓꽃 종을 분류하는
머신러닝 파이프라인을 구축합니다. 모델은 테스트 데이터에서 98.1% 정확도를 달성하며,
FastAPI를 통해 REST API로 배포됩니다.2. 주요 기능 (Features)
## 주요 기능
- 📊 Pandas와 Matplotlib을 이용한 탐색적 데이터 분석 (EDA)
- 🔧 데이터 전처리 및 특성 공학 파이프라인
- 🤖 다중 모델 비교 (로지스틱 회귀, 랜덤포레스트, SVM)
- 📈 GridSearchCV를 이용한 하이퍼파라미터 최적화
- 🚀 FastAPI를 이용한 REST API 배포
- 🐳 프로덕션 배포를 위한 Docker 컨테이너화3. 설치 지침
## 설치
### 요구사항
- Python 3.8+
- pip 또는 conda
### 빠른 시작
\`\`\`bash
# 저장소 클론
git clone https://github.com/username/iris-classification.git
cd iris-classification
# 가상환경 생성
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 의존성 설치
pip install -r requirements.txt
\`\`\`4. 사용 예제
## 사용 방법
### 모델 훈련
\`\`\`python
from src.model import train_model
from src.data import load_data
# 데이터 로드
X, y = load_data('data/iris.csv')
# 모델 훈련
model = train_model(X, y)
# 모델 저장
model.save('models/iris_classifier.pkl')
\`\`\`
### API로 예측
\`\`\`bash
# FastAPI 서버 시작
uvicorn main:app --reload
# 예측 요청
curl -X POST "http://localhost:8000/predict" \
-H "Content-Type: application/json" \
-d '{"sepal_length": 5.1, "sepal_width": 3.5, "petal_length": 1.4, "petal_width": 0.2}'
\`\`\`5. 프로젝트 구조
## 프로젝트 구조
\`\`\`
iris-classification/
├── data/
│ ├── raw/ # 원본 데이터
│ └── processed/ # 정제된 데이터
├── notebooks/
│ ├── 01-eda.ipynb
│ ├── 02-feature-engineering.ipynb
│ └── 03-modeling.ipynb
├── src/
│ ├── __init__.py
│ ├── data.py # 데이터 로딩
│ ├── features.py # 특성 공학
│ ├── model.py # 모델 훈련
│ └── evaluate.py # 평가 메트릭
├── models/
│ └── iris_classifier.pkl
├── tests/
│ ├── test_data.py
│ └── test_model.py
├── requirements.txt
├── README.md
├── LICENSE
└── .gitignore
\`\`\`6. 결과 및 메트릭
## 결과
| 모델 | 정확도 | 정밀도 | 재현율 | F1-Score |
|------|--------|--------|--------|----------|
| 로지스틱 회귀 | 97.5% | 0.976 | 0.975 | 0.975 |
| 랜덤포레스트 | **98.1%** | **0.981** | 0.981 | 0.981 |
| SVM | 97.8% | 0.978 | 0.978 | 0.978 |
**최고 성능 모델**: 랜덤포레스트 (테스트 정확도 98.1%)7. 재현 방법
## 결과 재현하기
처음부터 모든 결과를 재현하려면:
\`\`\`bash
# 1. 환경 설정
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# 2. 데이터 다운로드 (필요시)
python scripts/download_data.py
# 3. EDA 실행
jupyter notebook notebooks/01-eda.ipynb
# 4. 모델 훈련
python scripts/train_model.py
# 5. 평가
python scripts/evaluate_model.py
\`\`\`
**예상 결과**: 테스트 정확도 ≥ 98%8. 배포
## 배포
### 로컬 배포
\`\`\`bash
python main.py # FastAPI 서버 시작
\`\`\`
### Docker 배포
\`\`\`bash
docker build -t iris-classifier:1.0 .
docker run -p 8000:8000 iris-classifier:1.0
\`\`\`
### 클라우드 배포
- **Heroku**: `Procfile` 참고
- **AWS**: `aws/` 디렉토리의 CloudFormation 템플릿 참고
- **Google Cloud**: `gcp/` 디렉토리의 배포 스크립트 참고9. 기여 방법
## 기여하기
기여를 환영합니다! 다음 단계를 따라주세요:
1. 저장소 Fork
2. Feature branch 생성 (`git checkout -b feature/amazing-feature`)
3. 변경사항 커밋 (`git commit -m 'Add amazing feature'`)
4. Branch에 push (`git push origin feature/amazing-feature`)
5. Pull Request 열기
**요구사항:**
- PEP 8 코드 스타일 준수
- 모든 테스트 통과 (`pytest`)
- 문서 업데이트10. 라이선스 및 연락처
## 라이선스
이 프로젝트는 MIT License 하에 배포됩니다.
자세한 내용은 [LICENSE](LICENSE) 파일을 참고하세요.
## 저자
- **Your Name** - [@github_username](https://github.com/username)
## 문의
질문이나 제안이 있으시면 GitHub Issue를 열거나
your.email@example.com으로 이메일 주세요.requirements.txt Best Practices
# requirements.txt - 정확한 버전으로 재현성 보장
# 핵심 데이터 과학
pandas==1.5.3
numpy==1.24.3
scikit-learn==1.2.2
# 시각화
matplotlib==3.7.1
seaborn==0.12.2
# API 및 배포
fastapi==0.95.0
uvicorn==0.21.0
pydantic==1.10.7
# 유틸리티
joblib==1.2.0
python-dotenv==1.0.0
requests==2.31.0선택적: 개발용 요구사항
# requirements-dev.txt
-r requirements.txt # 프로덕션 요구사항 포함
# 개발 도구만
pytest==7.3.1
pytest-cov==4.0.0
jupyter==1.0.0
black==23.3.0
flake8==6.0.0
mypy==1.0.0사용:
pip install -r requirements-dev.txt # 개발 환경
pip install -r requirements.txt # 프로덕션 배포효과적인 README 체크리스트
- ✅ 명확한 프로젝트 제목
- ✅ 1-2 문단 설명 (비전공자도 이해 가능)
- ✅ 주요 기능 목록
- ✅ 설치 지침 (한 명령으로 실행 가능)
- ✅ 사용 예제 코드
- ✅ 프로젝트 구조 설명
- ✅ 성과 지표 또는 스크린샷
- ✅ 재현 방법
- ✅ 배포 지침
- ✅ 기여 방법
- ✅ 라이선스
- ✅ 연락처/저자
- ✅ 디버깅 팁 (선택)
- ✅ 참고 자료 링크 (선택)
옵션: 배지 (Badges)
README 상단에 프로젝트 상태를 시각화:
# 붓꽃 분류 프로젝트
[](https://github.com/username/project/actions)
[](https://codecov.io/gh/username/project)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)GitHub Best Practices
커밋 메시지 규칙
feat: 새로운 기능 추가
fix: 버그 수정
refactor: 코드 개선
docs: 문서 업데이트
test: 테스트 추가
좋은 예:
git commit -m "feat: 모델 하이퍼파라미터 최적화 with GridSearchCV"
git commit -m "fix: 데이터 로딩 경로 상대경로로 변경"
git commit -m "docs: README에 배포 지침 추가"
브랜칭 전략
# main 브랜치 직접 수정 금지!
# 항상 feature 브랜치에서 작업
git checkout -b feature/add-preprocessing
# ... 작업
git push origin feature/add-preprocessing
# GitHub에서 Pull Request 생성팀 협업 규칙
- main 브랜치: 배포 가능한 상태만
- develop 브랜치: 개발 중인 코드
- feature/* 브랜치: 개별 기능
Module 7 실전 체크리스트
- 저장소 초기화 및 README.md 작성
- 프로젝트 구조에 맞춰 디렉토리 생성
- requirements.txt 작성 (버전 고정)
- .gitignore 작성
- LICENSE.md 선택 및 추가
- CONTRIBUTING.md 작성 (선택)
- 모든 섹션이 README에 포함되어 있는지 확인
- 다른 사람이 5분 내에 실행 가능한지 테스트
- 코드 주석 및 docstring 추가
- 커밋 메시지 규칙 준수
- Main branch에 merge 전 Pull Request 리뷰
성공한 프로젝트 예시
성공한 GitHub 프로젝트의 공통점:
- 구조화된 섹션 제목
- 명확한 언어와 설명
- 실행 가능한 코드 예제
- 문제 해결 팁
- 완벽한 재현성
참고 자료
- GitHub 공식 문서: https://docs.github.com/repositories
- CONTRIBUTING 가이드: https://github.com/github/opensource.guide
- 라이선스 선택: https://choosealicense.com/
- Markdown 문법: https://www.markdownguide.org/
- Semantic Versioning: https://semver.org/
타 소스와의 연계
end-to-end-data-science-project (프로젝트 전체 구조) fastapi-ml-serving (API 배포) docker-ml-containerization (Docker 배포) exploratory-data-analysis-eda (EDA 개념)