개발 기여 가이드 (Contribution Guide) - WHS3-Fuzzk/SmartWebFuzzer GitHub Wiki

이 문서는 본 프로젝트에 기여하고자 하는 개발자들을 위한 안내서입니다.

1. 브랜치 전략 (GitFlow 기반)

본 프로젝트는 GitFlow 전략을 기반으로 사용합니다.
모든 작업 브랜치는 develop 를 기준으로 분기하며, 다음 규칙을 따릅니다.

참고 영상: (알아두면 개발팀장가능) GitFlow vs Trunk-based 협업방식

브랜치 이름 패턴 용도 Base Merge Target
main 배포 브랜치 (항상 안정된 버전) n/a n/a
develop 통합 개발 브랜치 n/a main (릴리스 시)
feat/<기능명> 새로운 기능 개발 develop develop

작업 흐름

  1. 브랜치 생성

    git checkout develop
git pull origin develop
git checkout -b feat/<기능명>

  2. 커밋 & 원격 푸시

    • 로컬 작업 후 원격(origin)으로 푸시하면 GitHub Actions (lint/format 검사: Pylint + Black) 가 실행됩니다.

  3. 상태 체크

    • 모든 검사에 통과한 커밋만 develop 브랜치로 병합할 수 있습니다.

  4. Merge 조건 (feat/<기능명> → develop)

    • 모든 CI 상태 체크 pass

  5. 릴리스 준비 (develop → main)

    • 스프린트 / 마일스톤 종료 시, develop을 main으로 Pull Request 합니다.
    • 2명 이상 팀원 승인(Review) 필수

2. 커밋 컨벤션 (Conventional Commits)

<타입>: <변경 요약>

예시:
feat: 로그인 API 추가
fix: 회원가입 시 이메일 중복 오류 수정
docs: README 오타 수정

자주 쓰는 타입

  • feat: 새로운 기능
  • fix: 버그 수정
  • docs: 문서 수정
  • style: 코드 포맷팅, 세미콜론 누락 등
  • refactor: 리팩토링
  • test: 테스트 추가 및 수정
  • chore: 빌드/환경 설정 등

3. 코드 스타일

# 린트 확인
pylint src/
# 코드 스타일 자동 적용
black .

4. 기여 전 체크리스트

  • 로컬에서 테스트 완료
  • 린트/포맷 통과

5. 개발 환경 구성: Docker 기반

본 프로젝트는 개발에 필요한 모든 인프라 서비스(PostgreSQL, Redis 등)를 Docker를 이용해 관리합니다.
이러한 서비스들은 별도로 설치할 필요 없이, docker-compose 명령어 한 번으로 자동 실행되도록 구성되어 있습니다.
이를 통해 로컬 OS(Mac, Windows, Linux 등)에 상관없이, 동일한 실행 절차와 매뉴얼로 개발 환경을 통일할 수 있습니다.

.env-template 파일을 .env로 복사 후 사용

cp .env-template .env

docker-compose.yml 기반 컨테이너 시작

# 의존 서비스 실행 (예: PostgreSQL, Redis 등)
# -d: 백그라운드에서 컨테이너를 실행. 로그 실시간 확인 필요 시 옵션 없이 실행
docker-compose up -d

컨테이너 상태 확인

docker-compose ps

컨테이너 중지

docker-compose stop

로그 확인

docker-compose logs -f
⚠️ **GitHub.com Fallback** ⚠️