From 9905972cfd6a3f05f5181bfc0fcdbba833d58b46 Mon Sep 17 00:00:00 2001 From: Youngtae Kim Date: Fri, 22 May 2026 15:45:29 +0900 Subject: [PATCH 1/5] Update baseline management guidelines in Korean --- doc/contribution/baseline-management-kr.md | 194 +++++++++++---------- 1 file changed, 105 insertions(+), 89 deletions(-) diff --git a/doc/contribution/baseline-management-kr.md b/doc/contribution/baseline-management-kr.md index a26a7a1a..b3799fa3 100644 --- a/doc/contribution/baseline-management-kr.md +++ b/doc/contribution/baseline-management-kr.md @@ -1,19 +1,26 @@ + --> + # 베이스라인 관리 규칙 +**최종 업데이트**: 2026-05-22 + **작성일**: 2026-04-30 **작성자**: Pullpiri CM팀 + + ## 목차 + 1. [개요](#1-개요) -2. [베이스라인 유형](#2-베이스라인-유형) -3. [베이스라인 설정 기준](#3-베이스라인-설정-기준) -4. [베이스라인 설정 절차](#4-베이스라인-설정-절차) -5. [베이스라인 이후 변경 관리](#5-베이스라인-이후-변경-관리) -6. [베이스라인 태그 명명 규칙](#6-베이스라인-태그-명명-규칙) +2. [베이스라인 태그 명명 규칙](#2-베이스라인-태그-명명-규칙) +3. [베이스라인 유형](#3-베이스라인-유형) +4. [베이스라인 설정 기준](#4-베이스라인-설정-기준) +5. [베이스라인 설정 절차](#5-베이스라인-설정-절차) +6. [베이스라인 이후 변경 관리](#6-베이스라인-이후-변경-관리) 7. [담당자 및 이해관계자](#7-담당자-및-이해관계자) 8. [베이스라인 관리 다이어그램](#8-베이스라인-관리-다이어그램) @@ -22,13 +29,43 @@ ## 1. 개요 베이스라인(Baseline)은 프로젝트 개발 과정의 특정 시점을 나타내는 기준점으로, CM(Configuration Management) 담당자에 의해 설정된다. -베이스라인 설정 이후 작업 산출물에 변경이 발생하는 경우, 해당 변경사항은 이해관계자의 **승인 및 공지** 절차를 반드시 거쳐야 한다. ---- +베이스라인 설정 이후 코드에 변경이 발생하는 경우, 해당 변경사항은 이해관계자의 **승인 및 공지** 절차를 반드시 거쳐야 한다. + + + +## 2. 베이스라인 태그 명명 규칙 + +[Semantic Versioning 2.0.0](https://semver.org/lang/ko/) 규칙을 기본으로 자체 규칙을 따른다. + +``` +v..[-<식별자>] +``` + +| 구성 요소 | 설명 | +| --------- | ------------------------------------------------------------ | +| `MAJOR` | 외부 조직 인도를 위한 목적으로 하위 호환성이 깨지는 변경 시 증가 | +| `MINOR` | 하위 호환성을 유지하는 신규 기능 추가 시 증가 | +| `PATCH` | 하위 호환성을 유지하는 버그 수정 시 증가 | +| `식별자` | 기타 비공식 베이스라인 구분자 (alpha, beta, rc1, milestone1 등) | + +### 예시 + +| 태그 | 의미 | +| ------------------- | ------------------------------------------------ | +| `v1.0.0` | 첫 번째 공식 릴리즈 | +| `v1.1.0` | 하위 호환 신규 기능 추가 공식 릴리즈 | +| `v1.1.1` | 버그 수정 패치 공식 릴리즈 | +| `v2.0.0` | 하위 비호환 주요 변경 공식 릴리즈 | +| `v1.2.0-alpha` | 내부 알파 테스트용 비공식 베이스라인 | +| `v1.2.0-rc1` | 릴리즈 후보(Release Candidate) 비공식 베이스라인 | +| `v1.2.0-milestone1` | 내부 마일스톤용 비공식 베이스라인 | + -## 2. 베이스라인 유형 -### 2.1 공식 베이스라인 (Official Baseline) +## 3. 베이스라인 유형 + +### 3.1 메이저 베이스라인 (Major Baseline) - **정의**: 외부 조직(고객사, 파트너 등)에 릴리즈하기 위한 베이스라인 - **대상 브랜치**: `main` @@ -37,32 +74,40 @@ - **GitHub 태그 형식**: `v..` (예: `v1.0.0`) - **GitHub Release**: 공식 베이스라인 설정 시 GitHub Release 페이지에 릴리즈 노트 작성 필수 -### 2.2 비공식 베이스라인 (Unofficial Baseline) +### 3.2 마이너 베이스라인 (Minor Baseline) - **정의**: LGE 내부 목표 달성 또는 개발 마일스톤 표시를 위한 베이스라인 - **대상 브랜치**: `main` 또는 특정 기능 브랜치 - **생성 주체**: CM 담당자 또는 개발 리드 - **승인 요건**: 팀 내 관련 담당자 승인 +- **GitHub 태그 형식**: `v.. (예: `v1.1.0`, `v1.2.1`) + +### 3.3 비공식 베이스라인 (Unofficial Baseline) + +- **정의**: Non-safety 영역을 다루는 범위 내에서 기능 안전과 관련 없는 목적을 위해 긴급히 수정을 반영하기 위한 베이스라인. 목적 달성 후 폐기 원칙 +- **대상 브랜치**: 특정 기능 브랜치 +- **생성 주체**: CM 담당자 +- **승인 요건**: CM 담당자 승인 - **GitHub 태그 형식**: `v..-<식별자>` (예: `v1.0.0-alpha`, `v1.1.0-milestone1`) ---- -## 3. 베이스라인 설정 기준 -### 3.1 공식 베이스라인 설정 기준 +## 4. 베이스라인 설정 기준 + +### 4.1 메이저 베이스라인 설정 기준 다음 조건이 모두 충족될 때 공식 베이스라인을 설정한다. -| 조건 | 세부 내용 | -|------|----------| -| 기능 구현 완료 | 해당 릴리즈의 모든 필수 기능(FEATURE 이슈) 구현 및 PR 머지 완료 | -| 테스트 통과 | 단위 테스트, 통합 테스트 모두 통과 (`test:passed` 라벨 확인) | -| 코드 리뷰 완료 | 모든 변경사항에 대해 리뷰어 1인 이상 승인 완료 | -| 빌드 성공 | CI 파이프라인 빌드 성공 확인 | -| 문서 업데이트 | `CHANGELOG`, `README`, API 문서 등 관련 문서 최신화 | -| 이해관계자 승인 | 외부 릴리즈 전 이해관계자 전원 서면(또는 이슈) 승인 | +| 조건 | 세부 내용 | +| --------------- | ------------------------------------------------------------ | +| 기능 구현 완료 | 해당 릴리즈의 모든 필수 기능(FEATURE 이슈) 구현 및 PR 머지 완료 | +| 테스트 통과 | 단위 테스트, 통합 테스트 모두 통과 (`test:passed` 라벨 확인) | +| 코드 리뷰 완료 | 모든 변경사항에 대해 리뷰어 1인 이상 승인 완료 | +| 빌드 성공 | CI 파이프라인 빌드 성공 확인 | +| 문서 업데이트 | `CHANGELOG`, `README`, API 문서 등 관련 문서 최신화 | +| 이해관계자 승인 | 외부 릴리즈 전 이해관계자 전원 서면(또는 이슈) 승인 | -### 3.2 비공식 베이스라인 설정 기준 +### 4.2 마이너 베이스라인 설정 기준 다음 중 하나 이상의 조건에 해당할 때 비공식 베이스라인을 설정한다. @@ -71,114 +116,84 @@ - 팀 내 점검 또는 데모를 위한 스냅샷 필요 - 외부 릴리즈 전 사전 검증(RC, alpha, beta) 목적 ---- -## 4. 베이스라인 설정 절차 -### 4.1 공식 베이스라인 설정 절차 +## 5. 베이스라인 설정 절차 + +### 5.1 메이저 베이스라인 설정 절차 + +1. **사전 검토**: CM 담당자가 [4.1 설정 기준](#41-메이저-베이스라인-설정-기준)의 모든 항목을 확인 -1. **사전 검토**: CM 담당자가 [3.1 설정 기준](#31-공식-베이스라인-설정-기준)의 모든 항목을 확인 2. **이슈 등록**: GitHub에 베이스라인 설정 이슈 등록 + - 제목: `[TASK] v<버전> 공식 베이스라인 설정` - 라벨: `type:task`, `priority:critical` + 3. **이해관계자 승인**: 이슈 또는 별도 채널을 통해 이해관계자 승인 획득 + 4. **태그 생성 및 푸시**: + ```bash git tag v.. git push origin v.. ``` + 5. **GitHub Release 작성**: GitHub Release 페이지에서 해당 태그로 릴리즈 노트 작성 + 6. **공지**: 이해관계자 및 개발팀 전체에 베이스라인 설정 완료 공지 + 7. **이슈 종료**: 베이스라인 설정 이슈 종료 -### 4.2 비공식 베이스라인 설정 절차 +### 5.2 비공식 베이스라인 설정 절차 1. **사전 검토**: 팀 내 담당자 승인 확인 + 2. **태그 생성 및 푸시**: + ```bash git tag v..-<식별자> git push origin v..-<식별자> ``` + 3. **공지**: 팀 내 관련 담당자에게 베이스라인 설정 공지 (이슈 코멘트 또는 메신저) ---- -## 5. 베이스라인 이후 변경 관리 + +## 6. 베이스라인 이후 변경 관리 베이스라인 설정 이후에는 해당 베이스라인 기준의 작업 산출물에 변경이 발생하더라도 **반드시 아래 절차를 준수**해야 한다. -### 5.1 변경 요청 절차 +### 6.1 변경 요청 절차 1. **변경 이슈 등록**: 변경이 필요한 내용을 GitHub 이슈로 등록 - 제목: `[BUG]` 또는 `[FEATURE]` 유형으로 등록 - 본문에 변경 이유, 영향 범위, 위험도 명시 2. **영향 분석**: CM 담당자 및 관련 개발자가 변경의 영향 범위 분석 3. **이해관계자 승인**: - - 공식 베이스라인 대상 변경: 이해관계자 전원 승인 필수 - - 비공식 베이스라인 대상 변경: 팀 내 담당자 승인 + - 메이저 베이스라인 대상 변경: 이해관계자 전원 승인 필수 + - 마이너 베이스라인 대상 변경: 팀 내 담당자 승인 4. **변경 구현**: 승인된 이슈 기반으로 기능 브랜치에서 개발 및 PR 생성 5. **검토 및 머지**: 코드 리뷰 및 CI 통과 후 머지 6. **새 베이스라인 설정** (필요 시): 패치 버전을 올려 새 베이스라인 설정 -### 5.2 핫픽스(Hotfix) 처리 - -공식 베이스라인 배포 후 긴급 결함 발생 시: - -1. `fix/<이슈번호>-<설명>` 브랜치를 해당 베이스라인 태그에서 생성: - ```bash - git checkout -b fix/<이슈번호>-<설명> <베이스라인-태그> - ``` -2. 버그 수정 후 PR 생성, 긴급 리뷰 진행 -3. `main` 브랜치에 머지 후 패치 버전 베이스라인(`v..`) 설정 -4. 이해관계자 및 고객사 공지 - -### 5.3 변경 금지 사항 +### 6.2 변경 금지 사항 - 승인 없이 공식 베이스라인 태그 삭제 또는 재작성(force push) 금지 - 베이스라인 태그가 가리키는 커밋의 히스토리 변경 금지 - 이해관계자 승인 없이 공식 베이스라인 산출물 배포 금지 ---- - -## 6. 베이스라인 태그 명명 규칙 -[Semantic Versioning 2.0.0](https://semver.org/lang/ko/) 규칙을 따른다. - -``` -v..[-<식별자>] -``` - -| 구성 요소 | 설명 | -|-----------|------| -| `MAJOR` | 하위 호환성이 깨지는 변경 시 증가 | -| `MINOR` | 하위 호환성을 유지하는 신규 기능 추가 시 증가 | -| `PATCH` | 하위 호환성을 유지하는 버그 수정 시 증가 | -| `식별자` | 비공식 베이스라인 구분자 (alpha, beta, rc1, milestone1 등) | - -### 예시 - -| 태그 | 의미 | -|------|------| -| `v1.0.0` | 첫 번째 공식 릴리즈 | -| `v1.1.0` | 하위 호환 신규 기능 추가 공식 릴리즈 | -| `v1.1.1` | 버그 수정 패치 공식 릴리즈 | -| `v2.0.0` | 하위 비호환 주요 변경 공식 릴리즈 | -| `v1.2.0-alpha` | 내부 알파 테스트용 비공식 베이스라인 | -| `v1.2.0-rc1` | 릴리즈 후보(Release Candidate) 비공식 베이스라인 | -| `v1.2.0-milestone1` | 내부 마일스톤용 비공식 베이스라인 | - ---- ## 7. 담당자 및 이해관계자 -| 역할 | 책임 | -|------|------| -| **CM 담당자** | 베이스라인 설정·태그 생성·공지, 변경 요청 접수 및 영향 분석 주도 | -| **개발 리드** | 기능 완료 및 품질 기준 충족 확인, 비공식 베이스라인 승인 | -| **이해관계자** | 공식 베이스라인 설정 및 변경 승인 | -| **개발자** | 변경 이슈 등록, 변경 구현 및 PR 생성 | +| 역할 | 책임 | +| -------------- | ------------------------------------------------------------ | +| **CM 담당자** | 베이스라인 설정·태그 생성·공지, 변경 요청 접수 및 영향 분석 주도 | +| **개발 리드** | 기능 완료 및 품질 기준 충족 확인, 비공식 베이스라인 승인 | +| **이해관계자** | 공식 베이스라인 설정 및 변경 승인 | +| **개발자** | 변경 이슈 등록, 변경 구현 및 PR 생성 | + ---- ## 8. 베이스라인 관리 다이어그램 @@ -189,7 +204,7 @@ v..[-<식별자>] ↓ CM 담당자 사전 검토 (기준 항목 확인) ↓ -베이스라인 설정 이슈 등록 +베이스라인 설정 이슈 Open ↓ 이해관계자 승인 획득 ↓ @@ -201,9 +216,11 @@ GitHub Release 작성 (공식 베이스라인만 해당) ↓ 이해관계자 공지 ↓ -이슈 종료 +베이스라인 설정 이슈 Close ``` + + ### 베이스라인 이후 변경 흐름 ``` @@ -229,12 +246,11 @@ main 브랜치 머지 ### 버전 이력 예시 ``` -main ──●──────●────────●────────────────────────────► - │ │ │ - v1.0.0 v1.1.0 v1.1.1 - (공식BL) (공식BL) (핫픽스BL) +main ──●──────●────────────────────────────────────► + │ │ + v1.0.0 v1.1.0 + (공식BL) (공식BL) │ └──► model/vehicle-x1 (모델 브랜치) ``` ---- From 91c7221fe465e4aac6bf34ea4285ee621b7c1061 Mon Sep 17 00:00:00 2001 From: Youngtae Kim Date: Fri, 22 May 2026 15:49:22 +0900 Subject: [PATCH 2/5] Create baseline-management.en.md for guidelines Added comprehensive baseline management rules document. --- doc/contribution/baseline-management.en.md | 236 +++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 doc/contribution/baseline-management.en.md diff --git a/doc/contribution/baseline-management.en.md b/doc/contribution/baseline-management.en.md new file mode 100644 index 00000000..96f6cae8 --- /dev/null +++ b/doc/contribution/baseline-management.en.md @@ -0,0 +1,236 @@ + + +# Baseline Management Rules + +**Last Updated**: 2026-05-22 + +**Created On**: 2026-04-30 +**Author**: Pullpiri CM Team + +## Table of Contents + +1. [Overview](#1-overview) +2. [Baseline Tag Naming Convention](#2-baseline-tag-naming-convention) +3. [Baseline Types](#3-baseline-types) +4. [Baseline Criteria](#4-baseline-criteria) +5. [Baseline Procedure](#5-baseline-procedure) +6. [Change Management After Baseline](#6-change-management-after-baseline) +7. [Roles and Stakeholders](#7-roles-and-stakeholders) +8. [Baseline Management Diagrams](#8-baseline-management-diagrams) + +--- + +## 1. Overview + +A baseline is a reference point that represents a specific point in the project development lifecycle, and it is established by the CM (Configuration Management) manager. + +If any code changes occur after a baseline is established, those changes must go through the stakeholder **approval and notification** process. + +## 2. Baseline Tag Naming Convention + +Pullpiri follows its own convention based on [Semantic Versioning 2.0.0](https://semver.org/). + +```text +v..[-] +``` + +| Element | Description | +| ------------ | --------------------------------------------------------------------------- | +| `MAJOR` | Incremented for incompatible changes intended for external organization delivery | +| `MINOR` | Incremented when backward-compatible features are added | +| `PATCH` | Incremented for backward-compatible bug fixes | +| `identifier` | Additional unofficial baseline qualifier (alpha, beta, rc1, milestone1, etc.) | + +### Examples + +| Tag | Meaning | +| ------------------- | ---------------------------------------------------- | +| `v1.0.0` | First official release | +| `v1.1.0` | Official release with backward-compatible new features | +| `v1.1.1` | Official patch release for bug fixes | +| `v2.0.0` | Official major release with incompatible changes | +| `v1.2.0-alpha` | Unofficial baseline for internal alpha testing | +| `v1.2.0-rc1` | Unofficial baseline for release candidate | +| `v1.2.0-milestone1` | Unofficial baseline for internal milestone | + +## 3. Baseline Types + +### 3.1 Major Baseline + +- **Definition**: A baseline for release to external organizations (customers, partners, etc.) +- **Target Branch**: `main` +- **Created By**: CM manager +- **Approval Requirement**: Approval from all stakeholders is required +- **GitHub Tag Format**: `v..` (e.g., `v1.0.0`) +- **GitHub Release**: When establishing an official baseline, release notes must be created on the GitHub Release page + +### 3.2 Minor Baseline + +- **Definition**: A baseline for achieving internal LGE goals or marking development milestones +- **Target Branch**: `main` or a specific feature branch +- **Created By**: CM manager or development lead +- **Approval Requirement**: Approval from relevant team members +- **GitHub Tag Format**: `v..` (e.g., `v1.1.0`, `v1.2.1`) + +### 3.3 Unofficial Baseline + +- **Definition**: A baseline to urgently reflect fixes for purposes unrelated to functional safety, within a scope that handles non-safety domains. As a principle, it should be discarded after the objective is achieved. +- **Target Branch**: A specific feature branch +- **Created By**: CM manager +- **Approval Requirement**: CM manager approval +- **GitHub Tag Format**: `v..-` (e.g., `v1.0.0-alpha`, `v1.1.0-milestone1`) + +## 4. Baseline Criteria + +### 4.1 Criteria for Major Baseline + +An official baseline is established only when all of the following conditions are met. + +| Condition | Details | +| ---------------------- | ----------------------------------------------------------------------- | +| Feature implementation completed | All required features (FEATURE issues) for the release are implemented and merged via PR | +| Tests passed | Both unit and integration tests are passed (`test:passed` label verified) | +| Code review completed | At least one reviewer approval completed for all changes | +| Build successful | CI pipeline build success verified | +| Documentation updated | Related documents updated (`CHANGELOG`, `README`, API docs, etc.) | +| Stakeholder approval | Written (or issue-based) approval from all stakeholders before external release | + +### 4.2 Criteria for Minor Baseline + +An unofficial baseline is established when one or more of the following conditions are met. + +- Internal milestone reached (end of sprint, transition of development phase, etc.) +- Development and integration of a major feature branch completed +- Snapshot needed for internal review or demo +- Pre-validation (RC, alpha, beta) required before external release + +## 5. Baseline Procedure + +### 5.1 Major Baseline Procedure + +1. **Pre-check**: CM manager verifies all items in [4.1 Criteria for Major Baseline](#41-criteria-for-major-baseline) + +2. **Issue creation**: Create a baseline issue on GitHub + + - Title: `[TASK] Set official baseline for v` + - Labels: `type:task`, `priority:critical` + +3. **Stakeholder approval**: Obtain stakeholder approval through the issue or a separate channel + +4. **Create and push tag**: + + ```bash + git tag v.. + git push origin v.. + ``` + +5. **Write GitHub Release**: Create release notes for the tag on the GitHub Release page + +6. **Notification**: Notify all stakeholders and the development team that baseline setup is complete + +7. **Issue close**: Close the baseline setup issue + +### 5.2 Unofficial Baseline Procedure + +1. **Pre-check**: Confirm approval from relevant team members + +2. **Create and push tag**: + + ```bash + git tag v..- + git push origin v..- + ``` + +3. **Notification**: Notify relevant team members of baseline setup (issue comment or messenger) + +## 6. Change Management After Baseline + +After a baseline is established, even if changes occur in deliverables based on that baseline, the following procedure **must be followed**. + +### 6.1 Change Request Procedure + +1. **Create change issue**: Register required changes as a GitHub issue + - Title: Register with `[BUG]` or `[FEATURE]` type + - Body: Specify reason for change, impact scope, and risk level +2. **Impact analysis**: CM manager and relevant developers analyze the impact scope of the change +3. **Stakeholder approval**: + - Changes to major baseline targets: Approval from all stakeholders required + - Changes to minor baseline targets: Approval from relevant team members +4. **Implement change**: Develop in a feature branch and create PR based on approved issue +5. **Review and merge**: Merge after code review and CI pass +6. **Set new baseline** (if needed): Increase patch version and set a new baseline + +### 6.2 Prohibited Changes + +- Deleting or rewriting (force push) official baseline tags without approval is prohibited +- Changing history of the commit pointed to by a baseline tag is prohibited +- Distributing official baseline deliverables without stakeholder approval is prohibited + +## 7. Roles and Stakeholders + +| Role | Responsibility | +| ---------------- | -------------------------------------------------------------------- | +| **CM Manager** | Establish baseline, create tags, send notifications, lead intake and impact analysis of change requests | +| **Dev Lead** | Verify feature completion and quality criteria, approve unofficial baselines | +| **Stakeholders** | Approve official baseline setup and changes | +| **Developers** | Register change issues, implement changes, and create PRs | + +## 8. Baseline Management Diagrams + +### Baseline Setup Flow + +```text +Development complete and tests passed + ↓ +CM pre-check (verify criteria items) + ↓ +Open baseline setup issue + ↓ +Obtain stakeholder approval + ↓ +Create and push Git tag + - Official: v.. + - Unofficial: v..- + ↓ +Write GitHub Release (official baseline only) + ↓ +Notify stakeholders + ↓ +Close baseline setup issue +``` + +### Post-baseline Change Flow + +```text +Change requirement identified + ↓ +Create change issue (BUG/FEATURE) + ↓ +Impact analysis (CM manager + developers) + ↓ +Stakeholder approval + ↓ +Implement change in feature branch + ↓ +Create PR → Review → CI pass + ↓ +Merge into main branch + ↓ +Set new baseline (if needed) + ↓ +Notify stakeholders +``` + +### Version History Example + +```text +main ──●──────●────────────────────────────────────► + │ │ + v1.0.0 v1.1.0 + (Official BL) (Official BL) + │ + └──► model/vehicle-x1 (model branch) +``` From b02880370d544a8c6c095f21234db7c300d704ab Mon Sep 17 00:00:00 2001 From: Youngtae Kim Date: Thu, 4 Jun 2026 10:18:27 +0900 Subject: [PATCH 3/5] Revise baseline management documentation Updated definitions and criteria for major and minor baselines, including changes to approval requirements and procedures. Revised baseline procedures and prohibited changes for clarity. --- doc/contribution/baseline-management.en.md | 75 ++-------------------- 1 file changed, 7 insertions(+), 68 deletions(-) diff --git a/doc/contribution/baseline-management.en.md b/doc/contribution/baseline-management.en.md index 96f6cae8..bf9adb9b 100644 --- a/doc/contribution/baseline-management.en.md +++ b/doc/contribution/baseline-management.en.md @@ -60,7 +60,7 @@ v..[-] ### 3.1 Major Baseline -- **Definition**: A baseline for release to external organizations (customers, partners, etc.) +- **Definition**: A baseline for achieving internal LGE goals or marking development milestones - **Target Branch**: `main` - **Created By**: CM manager - **Approval Requirement**: Approval from all stakeholders is required @@ -69,7 +69,7 @@ v..[-] ### 3.2 Minor Baseline -- **Definition**: A baseline for achieving internal LGE goals or marking development milestones +- **Definition**: A baseline for internal review, pre-release validation, or incorporating minor, non-functional code updates - **Target Branch**: `main` or a specific feature branch - **Created By**: CM manager or development lead - **Approval Requirement**: Approval from relevant team members @@ -89,85 +89,24 @@ v..[-] An official baseline is established only when all of the following conditions are met. -| Condition | Details | -| ---------------------- | ----------------------------------------------------------------------- | -| Feature implementation completed | All required features (FEATURE issues) for the release are implemented and merged via PR | -| Tests passed | Both unit and integration tests are passed (`test:passed` label verified) | -| Code review completed | At least one reviewer approval completed for all changes | -| Build successful | CI pipeline build success verified | -| Documentation updated | Related documents updated (`CHANGELOG`, `README`, API docs, etc.) | -| Stakeholder approval | Written (or issue-based) approval from all stakeholders before external release | +- Internal milestone reached (end of sprint, transition of development phase, etc.) +- Development and integration of a major feature branch completed ### 4.2 Criteria for Minor Baseline An unofficial baseline is established when one or more of the following conditions are met. -- Internal milestone reached (end of sprint, transition of development phase, etc.) -- Development and integration of a major feature branch completed +- Non-functional code changes and minor routine updates - Snapshot needed for internal review or demo - Pre-validation (RC, alpha, beta) required before external release ## 5. Baseline Procedure -### 5.1 Major Baseline Procedure - -1. **Pre-check**: CM manager verifies all items in [4.1 Criteria for Major Baseline](#41-criteria-for-major-baseline) - -2. **Issue creation**: Create a baseline issue on GitHub - - - Title: `[TASK] Set official baseline for v` - - Labels: `type:task`, `priority:critical` - -3. **Stakeholder approval**: Obtain stakeholder approval through the issue or a separate channel - -4. **Create and push tag**: - - ```bash - git tag v.. - git push origin v.. - ``` - -5. **Write GitHub Release**: Create release notes for the tag on the GitHub Release page - -6. **Notification**: Notify all stakeholders and the development team that baseline setup is complete - -7. **Issue close**: Close the baseline setup issue - -### 5.2 Unofficial Baseline Procedure - -1. **Pre-check**: Confirm approval from relevant team members - -2. **Create and push tag**: - - ```bash - git tag v..- - git push origin v..- - ``` - -3. **Notification**: Notify relevant team members of baseline setup (issue comment or messenger) +image ## 6. Change Management After Baseline -After a baseline is established, even if changes occur in deliverables based on that baseline, the following procedure **must be followed**. - -### 6.1 Change Request Procedure - -1. **Create change issue**: Register required changes as a GitHub issue - - Title: Register with `[BUG]` or `[FEATURE]` type - - Body: Specify reason for change, impact scope, and risk level -2. **Impact analysis**: CM manager and relevant developers analyze the impact scope of the change -3. **Stakeholder approval**: - - Changes to major baseline targets: Approval from all stakeholders required - - Changes to minor baseline targets: Approval from relevant team members -4. **Implement change**: Develop in a feature branch and create PR based on approved issue -5. **Review and merge**: Merge after code review and CI pass -6. **Set new baseline** (if needed): Increase patch version and set a new baseline - -### 6.2 Prohibited Changes - -- Deleting or rewriting (force push) official baseline tags without approval is prohibited -- Changing history of the commit pointed to by a baseline tag is prohibited -- Distributing official baseline deliverables without stakeholder approval is prohibited +image ## 7. Roles and Stakeholders From d1bc6a065165dbd73695ca8ac20457afa095bd15 Mon Sep 17 00:00:00 2001 From: Chulhee Lee Date: Fri, 3 Jul 2026 14:54:24 +0900 Subject: [PATCH 4/5] Create doc/docs/developments_KO.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 대한민국 개발자를 위한 developments.md 파일의 한글 번역 버전 --- doc/docs/developments_KO.md | 253 ++++++++++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 doc/docs/developments_KO.md diff --git a/doc/docs/developments_KO.md b/doc/docs/developments_KO.md new file mode 100644 index 00000000..c43c1e54 --- /dev/null +++ b/doc/docs/developments_KO.md @@ -0,0 +1,253 @@ + + +# Pullpiri + +이 문서는 개발, 테스트, 정적 분석에 관한 정보를 담고 있습니다. + +## 개발 + +### 환경 설정 + +자세한 내용은 [설치 가이드](/doc/docs/getting-started.md#installation)를 참고하세요. + +### 빌드 + +컨테이너 사용을 우선으로 하지만, 직접 빌드도 가능합니다. (단, 시스템에 따라 빌드 오류가 발생할 수 있습니다.) +본 프로젝트는 [cargo](https://doc.rust-lang.org/cargo/)를 빌드 시스템으로 사용하며, 명령어는 [Makefile](/Makefile)로 래핑되어 있습니다. + +바이너리 및 기타 아티팩트(매뉴얼 페이지 등)는 다음 명령으로 빌드할 수 있습니다: + +```bash +# src 디렉토리에서 +make build +# 아래와 동일 +cd src/agent && cargo build +cd src/player && cargo build +cd src/server && cargo build +``` + +빌드가 성공하면 바이너리는 다음 위치에 생성됩니다: + +```bash +# 바이너리만 표시 +[root@HPC src]# ls agent/target/debug/ +nodeagent +[root@HPC src]# ls player/target/debug/ +actioncontroller statemanager filtergateway +[root@HPC src]# ls server/target/debug/ +apiserver monitoringserver policymanager +``` + +직접 실행도 가능하지만, 컨테이너 사용을 권장합니다. + +```bash +# 루트 디렉토리에서 +make image +make install +``` + +자세한 내용은 [시작하기](/doc/docs/getting-started.md)를 참고하세요. + +## 정적 분석 + +### [rustfmt](https://github.com/rust-lang/rustfmt) + +Rustfmt는 공식 Rust 스타일 가이드에 따라 Rust 코드를 포맷합니다. +코드베이스 전반의 일관성을 유지하고 코드를 읽고 리뷰하기 쉽게 만들어 줍니다. + +#### rustfmt 사용법 + +1단계: Rustfmt 설치. + +```bash +rustup component add rustfmt +``` + +2단계: 코드 포맷: 프로젝트 내 모든 `.rs` 파일을 재귀적으로 포맷합니다. + +```bash +# src 디렉토리에서 +make fmt +``` + +### [clippy](https://doc.rust-lang.org/nightly/clippy/) + +Clippy는 일반적인 실수를 잡아내고 Rust 코드를 개선하기 위한 lint 모음입니다. +소스 코드를 분석하여 관용적인 Rust 작성법, 성능 개선, 잠재적 버그에 대한 제안을 제공합니다. + +#### clippy 사용법 + +1단계: Clippy 설치. + +```bash +rustup component add clippy +``` + +2단계: Clippy 실행: 프로젝트에 대해 린터를 실행합니다. +경고와 코드 개선 제안을 보고합니다. + +```bash +# src 디렉토리에서 +make clippy +``` + +*선택사항*: 경고 자동 수정: clippy 경고에 대해 안전한 자동 수정을 적용합니다. + +```bash +# `Cargo.toml`이 위치한 디렉토리 (예: `src/server/apiserver`) +cargo clippy --fix +``` + +### [cargo audit](https://crates.io/crates/cargo-audit) - 보안 취약점 스캐너 + +Cargo Audit은 `Cargo.lock` 파일을 RustSec Advisory Database와 대조하여 +알려진 보안 취약점이 있는 크레이트를 검사합니다. +의존성 보안을 확보하는 데 도움을 줍니다. + +#### cargo-audit 사용법 + +1단계: Cargo Audit 설치. + +```bash +cargo install cargo-audit +``` + +2단계: 실행: 의존성 트리에서 알려진 취약점 및 오래된 크레이트를 검사합니다. + +```bash +# `Cargo.lock`이 위치한 디렉토리 (예: `src/server`, `src/player`, `src/agent`) +cargo audit +``` + +### [cargo deny](https://crates.io/crates/cargo-deny) - 의존성 & 라이선스 검사기 + +Cargo Deny는 프로젝트 의존성에 대한 정책을 적용하는 데 사용되며, 다음 문제를 검사합니다: + +- 중복 크레이트 +- 허용되지 않는 라이선스 +- 보안 취약점 +- 유지보수되지 않는 크레이트 + +#### cargo-deny 사용법 + +1단계: Cargo Deny 설치 + +```bash +cargo install cargo-deny +``` + +2단계: 설정 초기화 (신규 컴포넌트에만 해당) - +라이선스 정책, 금지 항목, 예외를 설정할 수 있는 기본 deny.toml 파일을 생성합니다. + +```bash +# `Cargo.toml`이 위치한 디렉토리 (예: `src/server/apiserver`) +# 대부분의 크레이트는 이미 완료되어 있습니다. +cargo deny init +``` + +3단계: 검사 실행 - +의존성 메타데이터를 분석하여 라이선스, 보안 권고, 중복 관련 문제를 보고합니다. + +```bash +# `Cargo.toml`이 위치한 디렉토리 (예: `src/server/apiserver`) +cargo deny check +``` + +### [cargo udeps](https://crates.io/crates/cargo-udeps) - 미사용 의존성 감지기 + +Cargo Udeps는 `Cargo.toml`에서 사용되지 않는 의존성을 식별합니다. 미사용 의존성은 프로젝트를 비대하게 만들고 불필요한 취약점에 노출시킬 수 있습니다. 이 도구는 Nightly Rust가 필요합니다. + +*주의* : rustc 1.86.0 이상이 필요합니다. (2025년 7월 18일 기준) + +#### cargo-udeps 사용법 + +1단계: Cargo Udeps 설치 + +```bash +cargo install cargo-udeps +rustup install nightly +``` + +2단계: Nightly 실행 - +미사용 의존성 검사기를 실행하여 사용되지 않는 패키지 목록을 출력합니다. + +```bash +cargo +nightly udeps +``` + +## 단위 테스트 + +단위 테스트는 다음 명령으로 실행할 수 있습니다: + +```bash +# `Cargo.toml`이 포함된 임의의 디렉토리에서 +cargo test +``` + +## 통합 테스트 + +일부 `Pullpiri` 모듈에는 `tests` 폴더가 있습니다. + +```bash +# src/server/apiserver 디렉토리에서 +[root@HPC apiserver]# tree +. +├── apiserver.md +├── Cargo.toml +├── src +...... +└── tests + ├── api_integration.rs + ├── apiserver_init.rs + ├── filtergateway_integration.rs + └── manager_integration.rs +``` + +통합 테스트에 대한 일반적인 정보는 [rust doc](https://doc.rust-lang.org/rust-by-example/testing/integration_testing.html)을 참고하세요. + +## [cargo tarpaulin](https://crates.io/crates/cargo-tarpaulin) - 코드 커버리지 + +cargo-tarpaulin은 Rust 프로젝트를 위한 코드 커버리지 도구입니다. +Rust 코드를 계측하고, 테스트를 실행한 후 테스트 중 어떤 코드 라인이 실행되었는지 보여주는 상세 보고서를 생성합니다. +단위 테스트와 통합 테스트를 포함한 다양한 Rust 테스트 전략을 지원합니다. + +### 설치 및 실행 + +cargo-tarpaulin을 사용하려면 먼저 설치가 필요합니다. +cargo를 통해 간단히 설치할 수 있습니다: + +```bash +cargo install cargo-tarpaulin + +# 설치 후 다음 명령으로 프로젝트에서 도구를 실행할 수 있습니다: +# `Cargo.toml`이 포함된 임의의 디렉토리에서 +cargo tarpaulin +``` + +## 포트 사용 + +`Pullpiri`는 47001 ~ 47099 범위의 포트를 사용합니다. + +```Text +gRPC용 +47001~ + +REST용 +~47099 + +etcd (기본값) +2379, 2380 +``` + +## 기타 문서 + +이 프로젝트의 문서 파일은 [doc](/doc/) 디렉토리에 위치하며, 다음을 포함합니다: + +- [시작하기](/doc/docs/getting-started.md): 실행 방법 +- [예제](/examples/README.md): 예제 수행을 위한 모든 파일과 가이드가 포함된 디렉토리 +- (Deprecated) ~~[pullpiri.drawio](/doc/images/pullpiri.drawio): +Pullpiri에 사용된 모든 다이어그램이 포함된 파일~~ From bd06fc313395b4b201888c25178b3635d6196bc9 Mon Sep 17 00:00:00 2001 From: Chulhee Lee Date: Fri, 3 Jul 2026 15:19:33 +0900 Subject: [PATCH 5/5] docs: add Korean translation of getting-started.md This pull request adds a new Korean development document. --- doc/docs/getting-started_KO.md | 125 +++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 doc/docs/getting-started_KO.md diff --git a/doc/docs/getting-started_KO.md b/doc/docs/getting-started_KO.md new file mode 100644 index 00000000..5d1443e7 --- /dev/null +++ b/doc/docs/getting-started_KO.md @@ -0,0 +1,125 @@ + + +# 시작하기 + +## 시스템 요구사항 + +Pullpiri는 Ubuntu 24.04에서 테스트되었습니다. + +[Podman](https://podman.io/)은 컨테이너 런타임으로 사용되므로 반드시 설치되어 있어야 합니다 (Pullpiri는 버전 4.0.0 이상의 Podman이 필요합니다). +또한 컨테이너를 사용하지 않고 테스트하려면 [Rust](https://www.rust-lang.org)가 필요합니다. + +## 사전 정보 + +### Pullpiri 설정 + +설정을 위한 `settings.yaml` 파일이 있습니다. 이 파일은 설치 중에 `/etc/piccolo/settings.yaml` 경로에 자동으로 생성됩니다. + +```yaml +yaml_storage: /etc/piccolo/yaml +piccolo_cloud: http://0.0.0.0:41234 +host: + name: HPC + ip: 0.0.0.0 + type: bluechi +guest: +# - name: ZONE +# ip: 192.168.0.1 +# type: nodeagent +dds: + idl_path: src/vehicle/dds/idl + domain_id: 100 + # Removed out_dir - will use Cargo's default OUT_DIR +``` + +- yaml_storage : Podman을 이용해 systemd 서비스를 생성하기 위해 `.kube` 및 `.yaml` 파일이 필요합니다. +- piccolo_cloud : `Packages`와 `scenarios`를 저장하는 저장소 주소입니다. +- host : `bluechi`를 통해 systemd 명령을 전달하기 위해 노드 이름이 필요합니다. +- guest : Bluechi 에이전트 노드 정보입니다. +- dds : 추후 업데이트 예정입니다. + +### Pullpiri 모듈 + +Pullpiri는 여러 모듈로 구성되어 있습니다. +각 모듈에 대한 자세한 내용은 [Structure](/doc/docs/developments.md#structure)를 참고하세요. +또한 [예제](/examples/README.md)가 도움이 될 것입니다. + +## 제한 사항 + +- 멀티 노드 시스템 및 그에 따른 노드 셀렉터는 아직 완전히 고려되지 않았습니다. +- 원활한 운영을 위해 selinux permissive 모드의 `root` 사용자로 운영하는 것을 권장합니다. +- `/etc/containers/systemd` 폴더는 Pullpiri systemd 서비스 파일에 사용됩니다. 이 경로는 변경할 수 없습니다. +- 아직 초기 버전이므로 컨테이너 시작/중지/업데이트에 시간이 오래 걸릴 수 있습니다. +- 그 외 다른 문제가 발생할 수 있습니다. + +## 설치 + +### 설치 전 준비사항 + +필요한 패키지 설치, 방화벽 비활성화, selinux permissive 설정이 필요합니다. + +```bash +# 방화벽 비활성화 +systemctl stop firewalld +systemctl disable firewalld +# 패키지 설치 +dnf install git-all make gcc -y +# selinux permissive 설정 +setenforce 0 +``` + +설정 변경에 대한 자세한 내용은 [설정](#pullpiri-설정)을 참고하세요. + +### 설치 과정 + +모든 Pullpiri 애플리케이션과 테스트 앱은 컨테이너 내에서 실행됩니다. +컨테이너에 익숙하다면 쉽게 사용할 수 있을 것입니다. +`Pullpiri`는 기본적으로 `podman play`를 사용합니다. +처음 사용하는 경우 [예제](/examples/README.md)를 먼저 따라해보는 것을 권장합니다. + +시작하기 전에 Pullpiri 컨테이너 이미지를 빌드해야 합니다. + +```sh +make builder +make image +``` + +*주의* - 성공적인 빌드를 위해서는 최소 20GB의 디스크 공간이 필요합니다. + +`apt update` 중 오류가 발생하면 DNS 네임서버를 확인하세요. + +시작하려면, + +```sh +make install +``` + +중지하려면, + +```sh +make uninstall +``` + +`podman ps` 명령으로 컨테이너 목록을 확인할 수 있습니다. (infra 컨테이너는 생략됩니다.) + +```Text +[root@master pullpiri]# podman ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +fd03b211e2ac gcr.io/etcd-development/etcd:v3.5.24 --data-dir=/etcd-... 32 seconds ago Up 32 seconds 2379-2380/tcp piccolo-server-etcd +c6fbbb6feca5 localhost/pullpiri-server:latest 32 seconds ago Up 31 seconds piccolo-server-apiserver +341edada2c33 localhost/pullpiri-agent:latest 31 seconds ago Up 31 seconds piccolo-agent-nodeagent +eee2153bb581 localhost/pullpiri-player:latest 31 seconds ago Up 30 seconds piccolo-player-filtergateway +8d8011a24b43 localhost/pullpiri-player:latest 31 seconds ago Up 30 seconds piccolo-player-actioncontroller + +[root@master images]# podman pod ps +POD ID NAME STATUS CREATED INFRA ID # OF CONTAINERS +cc169812bd3e piccolo-player Degraded About a minute ago fb8974d9ba47 4 +85eeff5e07cf piccolo-agent Running About a minute ago 518c9482ae00 2 +809508bfdc46 piccolo-server Degraded About a minute ago 1a738d6106f0 5 +``` + +[Makefile](/Makefile)도 참고하세요.