141 lines
7.2 KiB
Markdown
141 lines
7.2 KiB
Markdown
# 실용적 Repository 명명 규칙 가이드
|
|
|
|
본 가이드는 연구 조직의 디지털 자산을 체계적으로 관리하기 위한 Repository 명명 규칙을 정의합니다. 프로젝트 성격에 따라 **모노레포(Monorepo)**와 **독립 Repository**로 나누어 설명합니다.
|
|
|
|
---
|
|
|
|
## 1. 핵심 원칙
|
|
|
|
모든 Repository는 다음 세 가지 공통 원칙을 따릅니다.
|
|
|
|
1. **형식**: 소문자와 하이픈(`-`)만 사용합니다. (예: `my-project`)
|
|
2. **언어**: 글로벌 협업을 위해 영문으로 작성합니다.
|
|
3. **명확성**: 이름만으로 목적을 쉽게 파악할 수 있도록 명확하고 직관적으로 작성합니다.
|
|
|
|
---
|
|
|
|
## 2. 모노레포 vs. 독립 Repository
|
|
|
|
새로운 작업을 시작하기 전, 아래 표를 참고하여 프로젝트에 가장 적합한 Repository 구조를 선택하세요.
|
|
|
|
| 구분 | 모노레포 (Monorepo) | 독립 Repository |
|
|
| :--- | :--- | :--- |
|
|
| **핵심 개념** | 하나의 큰 프로젝트에 속한 모든 코드를 단일 Repository에서 관리 | 각 Repository가 명확하고 독립적인 목적을 가짐 |
|
|
| **이름 규칙**| 프로젝트명 (접두사/접미사 없음) | `xxx-핵심주제` (3글자 접두사 기반) |
|
|
| **사용 시점**| 웹, API, 문서 등 여러 컴포넌트가 긴밀하게 연결된 단일 제품/프로젝트 | 조직 공용 도구, 특정 목적의 분석, 논문, 가이드, 템플릿 등 |
|
|
| **장점** | 코드 재사용 용이, 일관된 버전 관리, 리팩토링 편리 | 명확한 소유권, 독립적인 빌드/배포, 가볍고 빠른 클론 속도 |
|
|
| **예시** | `research-portal` | `gui-git-workflow`, `anl-user-retention-2024`, `tpl-python-service` |
|
|
|
|
---
|
|
|
|
## 3. 독립 Repository 명명 규칙
|
|
|
|
독립 Repository는 `xxx-핵심주제` 구조를 따릅니다. 이 규칙은 Repository의 성격을 명확히 하고 검색을 용이하게 합니다.
|
|
|
|
### 접두사 요약
|
|
|
|
| 접두사 (Prefix) | 의미 (Meaning) | 사용 사례 (Use Case) |
|
|
| :--- | :--- | :--- |
|
|
| `tpl-` | Template | 새로운 프로젝트를 시작하기 위한 표준 구조/코드 |
|
|
| `anl-` | Analysis | 특정 시점의 데이터 분석 결과 및 코드 |
|
|
| `res-` | Research | 독립적인 연구 코드 |
|
|
| `ppr-` | Paper | 논문 재현을 위한 코드 |
|
|
| `tst-` | Test | 신기술, 라이브러리의 독립적 테스트 |
|
|
| `poc-` | Proof of Concept | 특정 기술에 대한 개념 검증 |
|
|
| `tol-` | Tool | 조직 전반에서 사용하는 공용 개발/운영 도구 |
|
|
| `inf-` | Infrastructure | 공용 인프라 관리 코드 (IaC) |
|
|
| `doc-` | Documentation | 조직 전체의 공식 기술/정책 문서 |
|
|
| `gui-` | Guide | 특정 절차나 워크플로우에 대한 가이드 |
|
|
| `lib-` | Library | 여러 프로젝트에서 공용으로 사용하는 라이브러리 |
|
|
| `dat-` | Data | 조직에서 관리하는 공용 데이터셋 |
|
|
|
|
### 접두사별 상세 가이드
|
|
|
|
#### 템플릿 (`tpl-`)
|
|
새로운 프로젝트의 보일러플레이트로 사용될 표준 구조 및 코드 템플릿입니다.
|
|
- **구조**: `tpl-{기술스택-또는-프로젝트유형}`
|
|
- **예시**:
|
|
- `tpl-python-service`: Python 기반 마이크로서비스 프로젝트 템플릿
|
|
- `tpl-react-web-app`: React 기반 웹 애플리케이션 표준 템플릿
|
|
|
|
#### 📊 데이터 분석 (`anl-`)
|
|
일회성이거나 특정 시점의 데이터 분석 결과 및 코드를 저장합니다.
|
|
- **구조**: `anl-{분석내용}-{연도/분기}`
|
|
- **예시**:
|
|
- `anl-user-retention-2024-q2`: 2024년 2분기 사용자 리텐션 분석
|
|
- `anl-market-research-gen-ai`: 생성형 AI 시장 조사 분석
|
|
|
|
#### 🔬 연구 및 논문 (`res-`, `ppr-`)
|
|
독립적인 순수 연구나 논문 재현을 위한 코드입니다.
|
|
- **구조**: `res-{연구주제}` 또는 `ppr-{논문제목-키워드}-{연도}`
|
|
- **예시**:
|
|
- `res-protein-folding-simulation`: 단백질 폴딩 시뮬레이션 연구
|
|
- `ppr-attention-is-all-you-need-2017`: "Attention Is All You Need" 논문 재현
|
|
|
|
#### 🧪 테스트 및 개념 검증 (`tst-`, `poc-`)
|
|
신기술, 라이브러리를 독립적으로 테스트하거나 아이디어의 실현 가능성을 검증합니다.
|
|
- **구조**: `tst-{테스트대상}` 또는 `poc-{검증개념}`
|
|
- **예시**:
|
|
- `tst-pytorch-vs-tensorflow`: PyTorch와 TensorFlow 성능 비교 테스트
|
|
- `poc-vector-db-search`: 벡터 DB를 활용한 시맨틱 검색 PoC
|
|
|
|
#### 🛠️ 도구 및 인프라 (`tol-`, `inf-`)
|
|
조직 전반에서 공용으로 사용되는 개발 도구나 인프라 관리 코드(IaC)입니다.
|
|
- **구조**: `tol-{도구목적}` 또는 `inf-{관리대상}`
|
|
- **예시**:
|
|
- `tol-data-anonymization`: 데이터 익명화 처리 스크립트
|
|
- `inf-kubernetes-cluster`: 공용 쿠버네티스 클러스터 설정 (Terraform)
|
|
|
|
#### 📜 문서 및 가이드 (`doc-`, `gui-`)
|
|
특정 프로젝트에 종속되지 않는 조직의 공식 문서나 프로세스 가이드입니다.
|
|
- **구조**: `doc-{문서성격}` 또는 `gui-{가이드주제}`
|
|
- **예시**:
|
|
- `doc-api-style-guide`: 조직의 API 스타일 가이드 문서
|
|
- `gui-onboarding-for-engineers`: 신규 엔지니어 온보딩 가이드
|
|
|
|
#### 📚 기타 (`lib-`, `dat-`)
|
|
- **`lib-{패키지명}`**: 여러 프로젝트에서 공용으로 사용하는 라이브러리
|
|
- 예: `lib-react-ui-kit`
|
|
- **`dat-{데이터설명}`**: 조직에서 관리하는 공용 데이터셋
|
|
- 예: `dat-korean-sentiment-corpus`
|
|
|
|
---
|
|
|
|
## 4. 모노레포 시작 가이드
|
|
|
|
모노레포 Repository 이름은 접두사 없이 프로젝트명을 그대로 사용합니다. (예: `research-portal`)
|
|
|
|
> **중요: 모노레포는 처음부터 만들지 마세요.**
|
|
>
|
|
> 일관성을 유지하고 초기 설정 시간을 줄이기 위해, 모든 모노레포 프로젝트는 반드시 사전에 정의된 **템플릿 Repository(`tpl-`)**에서 시작해야 합니다.
|
|
|
|
### 새로운 템플릿이 필요하다면?
|
|
만약 현재 프로젝트에 적합한 모노레포 템플릿이 없다면, 새로운 템플릿 생성을 제안할 수 있습니다.
|
|
|
|
1. **`gui-gitea-operation` 저장소**의 `Issues` 탭에서 새로운 이슈를 생성합니다.
|
|
2. **제목**은 `tpl-{템플릿 이름}`과 같이 제안하는 템플릿의 이름을 명시합니다.
|
|
3. **본문**에는 템플릿의 필요성, 기대 효과, 포함될 기술 스택 및 디렉토리 구조 등을 상세히 기입합니다.
|
|
4. 이슈에 **`Propose new gitea template` 레이블**을 추가하여 제안을 제출합니다.
|
|
|
|
담당자는 제안된 내용을 검토하여 템플릿 생성 여부를 결정합니다.
|
|
|
|
### 시작 절차
|
|
|
|
1. GitHub에서 승인된 `tpl-*` 템플릿 Repository로 이동합니다.
|
|
2. `Use this template` 버튼을 클릭하여 새로운 Repository를 생성합니다.
|
|
3. 새 Repository의 이름을 최종 프로젝트명으로 지정합니다. (예: `research-portal`)
|
|
|
|
#### 예시: `research-portal`
|
|
- **Repository 이름**: `research-portal`
|
|
- **내부 폴더 구조 (템플릿 제공)**:
|
|
```plaintext
|
|
research-portal/
|
|
├── .github/
|
|
├── apps/ # 애플리케이션 (웹, 문서 등)
|
|
│ ├── web/
|
|
│ └── docs-site/
|
|
├── packages/ # 공유 패키지 (UI 컴포넌트, 로거 등)
|
|
│ ├── ui-kit/
|
|
│ └── logger/
|
|
└── README.md
|
|
``` |