From d6784807f2ec750ef9a1f453ccc9d4f01568a1fe Mon Sep 17 00:00:00 2001 From: choibk Date: Sat, 24 Jan 2026 23:44:06 +0900 Subject: [PATCH] =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=97=85=EB=8D=B0?= =?UTF-8?q?=EC=9D=B4=ED=8A=B8:=20git=20=ED=83=9C=EA=B7=B8=20=EC=9E=91?= =?UTF-8?q?=EC=84=B1=20=EA=B7=9C=EC=B9=99=20->=20git=20=EC=9A=B4=EC=98=81?= =?UTF-8?q?=20=EA=B7=9C=EC=B9=99=20(=EC=88=98=EB=8F=99=20=EC=97=85?= =?UTF-8?q?=EB=8D=B0=EC=9D=B4=ED=8A=B8=20=EA=B0=80=EC=9D=B4=EB=93=9C=20?= =?UTF-8?q?=EC=B6=94=EA=B0=80)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/git 운영 규칙.md | 100 +++++++++++++++++++++++++++++++++++++ docs/git 태그 작성 규칙.md | 86 ------------------------------- 2 files changed, 100 insertions(+), 86 deletions(-) create mode 100644 docs/git 운영 규칙.md delete mode 100644 docs/git 태그 작성 규칙.md diff --git a/docs/git 운영 규칙.md b/docs/git 운영 규칙.md new file mode 100644 index 0000000..db7f379 --- /dev/null +++ b/docs/git 운영 규칙.md @@ -0,0 +1,100 @@ +# 🏷️ Git 운영 및 통합 업데이트 관리 규칙 + +이 문서는 Smart IMS 플랫폼의 **Git 운영 정책**, **태그 작성 규칙**, 그리고 **운영 서버 수동 업데이트 방법**을 설명합니다. + +--- + +## 1. 태그 메시지 작성 규칙 (Changelog 자동 생성) + +플랫폼의 업데이트 엔진은 태그 메시지의 **머리말(Prefix)**과 **리스트 기호(`-`, `*`)**를 분석하여 관리 페이지의 업데이트 히스토리를 생성합니다. + +### 📋 메시지 구조 +```text +[TYPE] 업데이트 제목 (한 줄 요약) +- 상세 변경 내용 1 +- 상세 변경 내용 2 +* 상세 변경 내용 3 +``` + +### 🏷️ 업데이트 타입 (TYPE) 정의 +| 키워드 | 업데이트 유형 | 시각적 표시 | 비고 | +|:--- |:--- |:--- |:--- | +| `[URGENT]` | **긴급/보안** | 빨간색 배너 | 최우선 업데이트 권장 | +| `[HOTFIX]` | **긴급 수정** | 빨간색 배너 | 버그 즉시 수정 건 | +| `[FEATURE]` | **기능 추가** | 남색(Indigo) | 새로운 기능 도입 | +| `[FIX]` | **일반 수정** | 회색(Slate) | 일반적인 버그 수정 | +| `[PATCH]` | **패치/보정** | 회색(Slate) | 마이너 품질 개선 | + +--- + +## 2. 개발 및 배포 절차 (Local → Remote) + +### STEP 1: 코드 변경 사항 커밋 및 푸시 +```powershell +git add . +git commit -m "릴리즈 준비: v0.3.5 패치" +git push origin main +``` + +### STEP 2: 어노테이티드 태그(Annotated Tag) 생성 +시스템 엔진이 메시지를 읽으려면 반드시 `-a` 옵션을 사용해야 합니다. +```powershell +git tag -a v0.3.5 -m "[PATCH] 시스템 안정화 패치 +- 원격 태그 동기화 로직 강화 +- API 캐시 방지 타임스탬프 도입" +``` + +### STEP 3: 원격 저장소에 태그 푸시 +```powershell +git push origin v0.3.5 +``` + +--- + +## 3. 운영 서버 수동 업데이트 방법 (Manual Update) + +웹 UI의 자동 업데이트가 불가능하거나 직접 서버에서 제어해야 할 경우 아래 명령어를 순서대로 실행합니다. + +### STEP 1: 최신 태그 정보 강제 동기화 +로컬 태그 캐시와 원격 저장소의 실제 태그를 일치시킵니다. +```powershell +git fetch origin +refs/tags/*:refs/tags/* --force --prune --prune-tags +``` + +### STEP 2: 대상 버전으로 체크아웃 +```powershell +# 모든 변경사항을 무시하고 강제로 특정 태그 버전으로 전환 +git checkout -f v0.3.5 +``` + +### STEP 3: 의존성 설치 및 빌드 (Root 경로) +```powershell +npm install +npm run build +``` + +### STEP 4: 서버 모듈 의존성 설치 및 재시작 (Server 경로) +```powershell +cd server +npm install +pm2 reload smartims-api +``` + +--- + +## 4. 유용한 Git 명령어 레퍼런스 + +* **태그 목록 확인**: `git tag -l` +* **최신 태그 정보 확인**: `git describe --tags --abbrev=0` +* **원격 태그 강제 덮어쓰기 (수정 시)**: + ```powershell + git tag -a v0.3.5 -f -m "수정된 메시지..." + git push origin v0.3.5 -f + ``` + +--- + +## 💡 주의사항 +1. **빌드 확인**: 운영 서버에서 수동 업데이트 시 `npm run build` 과정에서 에러가 없는지 반드시 확인해야 합니다. +2. **권한 차이**: 수동 업데이트 시 파일 권한 문제가 발생할 수 있으므로 가급적 서비스 실행 계정(예: `sokuree`)으로 진행하세요. +3. **No-Cache**: 업데이트 후 브라우저에 즉시 반영되지 않으면 서버의 `pm2 reload`가 정상적으로 수행되었는지 확인하세요. diff --git a/docs/git 태그 작성 규칙.md b/docs/git 태그 작성 규칙.md deleted file mode 100644 index e3b131e..0000000 --- a/docs/git 태그 작성 규칙.md +++ /dev/null @@ -1,86 +0,0 @@ -# 🏷️ Git 태그 작성 및 통합 업데이트 관리 규칙 - -이 문서는 Smart IMS 플랫폼의 자동 업데이트 엔진이 인식하는 **Git 태그 작성 규칙**과 기본적인 **Git 명령어** 활용법을 설명합니다. 본 플랫폼은 Git 태그의 메시지를 자동으로 파싱하여 관리 페이지의 업데이트 히스토리를 생성합니다. - ---- - -## 1. 태그 메시지 작성 규칙 (Convention) - -플랫폼의 업데이트 엔진은 태그 메시지의 **머리말(Prefix)**과 **리스트 기호(`-`, `*`)**를 분석합니다. - -### 📋 메시지 구조 -```text -[TYPE] 업데이트 제목 (한 줄 요약) -- 상세 변경 내용 1 -- 상세 변경 내용 2 -* 상세 변경 내용 3 -``` - -### 🏷️ 업데이트 타입 (TYPE) 정의 -메시지 첫 줄에 아래 대괄호 키워드를 포함하면 관리 페이지에서 시각적으로 구분됩니다. - -| 키워드 | 업데이트 유형 | 시각적 표시 | 비고 | -|:--- |:--- |:--- |:--- | -| `[URGENT]` | **긴급/보안** | 빨간색 배너 | 최우선 업데이트 권장 | -| `[HOTFIX]` | **긴급 수정** | 빨간색 배너 | 버그 즉시 수정 건 | -| `[FEATURE]` | **기능 추가** | 남색(Indigo) | 새로운 기능 도입 | -| `[FIX]` | **일반 수정** | 회색(Slate) | 일반적인 버그 수정 | -| `[PATCH]` | **패치/보정** | 회색(Slate) | 마이너 품질 개선 | - ---- - -## 2. 릴리즈 배포 절차 (명령어) - -새로운 버전을 배포할 때는 아래 순서대로 명령어를 실행합니다. - -### STEP 1: 코드 변경 사항 커밋 -```powershell -git add . -git commit -m "커밋 메시지 (태그와 별개)" -git push origin main -``` - -### STEP 2: 어노테이티드 태그(Annotated Tag) 생성 -시스템 엔진이 메시지를 읽으려면 반드시 `-a` 옵션을 사용하는 **Annotated Tag**여야 합니다. - -```powershell -# 예시: v0.3.5 버전 배포 시 -git tag -a v0.3.5 -m "[FEATURE] 보고서 출력 기능 도입 -- 자산 상세 페이지 PDF 저장 기능 추가 -- 정비 이력 엑셀 내보내기 필터 보강 -- 인쇄용 스타일 시트 최적화" -``` - -### STEP 3: 원격 저장소에 태그 푸시 -```powershell -# 특정 태그만 푸시 -git push origin v0.3.5 - -# 생성된 모든 로컬 태그 푸시 -git push origin --tags -``` - ---- - -## 3. 유용한 Git 명령어 레퍼런스 - -### 🔍 조회 관련 -* **태그 목록 확인**: `git tag -l` -* **특정 태그의 상세 메시지 확인**: `git show v0.3.5` -* **최신 태그 정보 확인**: `git describe --tags --abbrev=0` - -### 🛠️ 관리 관련 -* **태그 삭제 (로컬)**: `git tag -d v0.3.5` -* **태그 삭제 (원격)**: `git push origin :refs/tags/v0.3.5` -* **실수로 태그 메시지를 잘못 적었을 때 (수정)**: - ```powershell - git tag -a v0.3.5 -f -m "[FIX] 수정된 메시지 내용..." - git push origin v0.3.5 -f - ``` - ---- - -## 💡 주의사항 -1. **버전 넘버링**: `v0.0.0` 형식을 권장합니다 (예: `v0.3.4`). -2. **No-Cache**: 태그 푸시 후 관리 페이지에서 즉시 확인되지 않는 경우, 페이지 상단의 '새로고침' 아이콘을 눌러 원격 저장소와 동기화하세요. -3. **내용 입력**: `-` 또는 `*` 기호를 생략하면 해당 줄은 개별 리스트 항목으로 인식되지 않고 뭉쳐서 표시될 수 있습니다.