gui-gitea-operation/guide-readme/monorepo.md

모노레포(Monorepo) README 작성 가이드

모노레포는 여러 프로젝트(애플리케이션, 패키지)를 단일 저장소에서 관리하므로, 전체 구조와 각 컴포넌트의 상호작용을 명확히 안내하는 것이 중요합니다. 루트 README는 프로젝트의 진입점 역할을 해야 합니다.

---

1. 전체 구조 개요 (Repository Structure)

• 목적: 저장소의 폴더 구조를 시각적으로 보여주어 각 패키지와 애플리케이션의 위치를 빠르게 파악할 수 있도록 돕습니다.
• 예시:

  my-monorepo/
  ├── apps/
  │   ├── web-app/         # 사용자용 웹 애플리케이션
  │   └── admin-dashboard/ # 관리자용 대시보드
  ├── packages/
  │   ├── ui-kit/          # 공통 UI 컴포넌트
  │   └── data-models/     # 공유 데이터 모델
  └── README.md
  

• 팁: 각 폴더에 대한 간단한 설명을 덧붙여 이해를 돕습니다.

2. 컴포넌트별 가이드 (Per-Component Instructions)

• 목적: 각 app과 package의 개별적인 설정, 실행, 테스트 방법을 안내합니다.
• 구성:
  • apps/web-app:
    • 설명: 최종 사용자가 상호작용하는 기본 웹 애플리케이션입니다.
    • 실행: npm run dev --filter=web-app
    • 테스트: npm test --filter=web-app
  • packages/ui-kit:
    • 설명: 디자인 시스템과 재사용 가능한 UI 컴포넌트를 제공합니다.
    • 빌드: npm run build --filter=ui-kit
    • 스토리북: npm run storybook --filter=ui-kit
• 팁: 각 컴포넌트의 README.md로 연결되는 링크를 제공하여 상세 정보를 확인할 수 있도록 합니다.

3. 공통 스크립트 (Repository-wide Scripts)

• 목적: 저장소 전체에 적용되는 명령어를 중앙에서 관리하고 안내합니다.
• 예시:
  • npm install: 모든 패키지의 의존성을 한 번에 설치합니다.
  • npm run build:all: 모든 app과 package를 빌드합니다.
  • npm run test:all: 전체 테스트를 실행합니다.
  • npm run lint: 코드 스타일을 검사하고 수정합니다.

4. CI/CD 파이프라인 개요

• 목적: 코드 변경 사항이 어떻게 빌드, 테스트, 배포되는지 전체 흐름을 설명합니다.
• 포함 내용:
  • 트리거: 어떤 브랜치에 코드가 푸시되면 파이프라인이 실행되는지 명시합니다. (예: main, develop)
  • 주요 단계: 빌드, 유닛 테스트, E2E 테스트, 배포 등의 단계를 간략히 설명합니다.
  • 배포 환경: 개발(dev), 스테이징(staging), 프로덕션(production) 환경별 배포 정책을 안내합니다.

5. 버전 관리 및 릴리즈 전략

• 목적: 패키지 버전 업데이트와 릴리즈 과정을 안내하여 일관성을 유지합니다.
• 도구: Changesets 와 같은 도구를 사용한 버전 관리 방법을 설명합니다.
• 프로세스:
  1. feature 브랜치에서 npx changeset 명령어로 변경 사항을 기록합니다.
  2. main 브랜치에 병합되면, Changesets PR이 자동으로 생성됩니다.
  3. 해당 PR을 병합하면 버전이 업데이트되고 npm에 배포됩니다.

템플릿 활용: 모노레포는 tpl-monorepo-* 템플릿을 기반으로 생성하는 것을 권장합니다. 루트 README는 해당 템플릿의 사용법과 커스터마이징 방법을 포함해야 합니다.