Skip to content

Repository-rule.md

Latest commit

 

History

History
194 lines (135 loc) · 4.23 KB

Repository-rule.md

File metadata and controls

194 lines (135 loc) · 4.23 KB

Repository Rule

Repository Rule 은
저장소 전체를 어떤 기준으로 운영할지 정해두는 규칙이다.

branch, commit, push 같은 개별 규칙도 중요하지만
저장소 자체를 어떻게 구성하고 관리할지 정해두면
프로젝트를 훨씬 깔끔하게 유지할 수 있다.

1. 왜 필요한가

저장소 운영 규칙이 없으면
프로젝트 구조와 관리 방식이 제각각이 될 수 있다.

예를 들어 아래 같은 문제가 생길 수 있다.

  • 폴더 구조가 일관되지 않음
  • README 가 없어서 프로젝트 설명이 부족함
  • 민감한 파일이 올라감
  • main 에 직접 push 가 발생함
  • 필요 없는 파일이 계속 쌓임

그래서 저장소 전체 기준을 정해두는 것이 좋다.

2. 기본 원칙

저장소는
누가 봐도 구조와 사용 방법을 이해할 수 있게 관리하는 것이 좋다.

보통 아래를 기준으로 둔다.

  • 폴더 구조 정리
  • README 작성
  • .gitignore 설정
  • branch 운영 기준
  • 환경 파일 관리
  • 문서와 소스 구분

3. 폴더 구조 규칙 추천

프로젝트마다 다를 수 있지만
역할별로 구분하는 것이 좋다.

example

  • src/ : 소스 코드
  • docs/ : 문서
  • rule/ : Git 또는 프로젝트 운영 규칙
  • assets/ : 이미지, 아이콘, 정적 파일
  • tests/ : 테스트 코드
  • config/ : 설정 파일
  • README.md : 프로젝트 설명

4. README 규칙

README 는
저장소의 기본 설명서 역할을 한다.

가능하면 아래 내용을 포함하는 것이 좋다.

  • 프로젝트 이름
  • 프로젝트 설명
  • 실행 방법
  • 설치 방법
  • 폴더 구조
  • 주의 사항
  • 예시 화면 또는 예시 명령어

README 가 없으면
저장소를 처음 보는 사람이 이해하기 어렵다.

5. 환경 파일 규칙

1) .env 는 제외

민감한 정보가 들어갈 수 있으므로
.gitignore 에 넣는 것이 좋다.

2) .env.example 는 포함

필요한 환경 변수 이름만 적어둔 예시 파일은
공유하는 것이 좋다.

example:

  • .env 는 제외
  • .env.example 는 포함

6. branch 운영 규칙

1) main 은 안정 버전 유지

바로 작업하지 않고
완료된 작업만 merge 하는 것을 추천한다.

2) 작업은 별도 branch 에서 진행

예:

  • feat/login
  • fix/upload-error
  • docs/git-manual

3) merge 후 오래된 branch 정리

끝난 branch 는 삭제하는 것이 좋다.

7. 파일 관리 규칙

1) 자동 생성 파일 commit 금지

예:

  • build/
  • dist/
  • __pycache__/

2) 개인 설정 파일 commit 주의

예:

  • .vscode/
  • .idea/

3) 대용량 결과물은 신중하게 관리

필요 없는 실행 파일, 로그 파일은 올리지 않는 것이 좋다.

4) 문서와 코드 구분

문서 파일은 docs/ 나 rule/ 로 분리하면 보기 좋다.

8. 권장 운영 방식

recommended flow

  1. 저장소 생성
  2. 기본 폴더 구조 정리
  3. .gitignore 작성
  4. README.md 작성
  5. 필요하면 .env.example 작성
  6. 작업용 branch 생성
  7. commit / push / PR 흐름으로 운영

9. 협업 시 추천 규칙

1) main 직접 push 최소화

가능하면 PR 후 merge

2) commit 메시지 규칙 통일

예:

  • FEAT: add login page
  • FIX: correct path error

3) branch 이름 규칙 통일

예:

  • feat/login
  • docs/readme-update

4) 리뷰 후 merge 권장

특히 기능 추가나 구조 변경은
검토 후 merge 하는 것이 좋다.

10. 나쁜 예 / 좋은 예

bad

  • README 없음
  • .env push
  • main 에 직접 작업
  • 폴더 구조가 제각각임
  • 문서와 코드가 뒤섞여 있음

good

  • README 작성
  • .gitignore 설정
  • .env.example 제공
  • 역할별 폴더 구분
  • 작업은 branch 에서 진행 후 merge

11. 한 줄 정리

좋은 저장소 운영 규칙은
프로젝트 구조와 작업 흐름을 일정하게 유지해서 누구나 쉽게 이해하고 관리할 수 있게 만드는 것이다.