From 3f1785206b52517fbcbab67fdf478200d05f8509 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Mon, 23 Feb 2026 13:09:57 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20[academy]=20Git=20=EC=A0=95=EC=B1=85=20?= =?UTF-8?q?=EB=B0=B1=EA=B3=BC=EC=82=AC=EC=A0=84=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 10개 섹션: 버전관리/기초/원격/브랜치/커밋/협업/충돌/SAM정책/.gitignore/배포 - teal 테마, SVG 일러스트 10개, 도움말 풍선 - 전문용어 툴팁 30개 (git-policy 도메인) --- .gitignore | 3 + app/Http/Controllers/AcademyController.php | 18 + public/images/academy/git-policy/1.svg | 114 ++ public/images/academy/git-policy/10.svg | 232 +++ public/images/academy/git-policy/2.svg | 135 ++ public/images/academy/git-policy/3.svg | 138 ++ public/images/academy/git-policy/4.svg | 120 ++ public/images/academy/git-policy/5.svg | 117 ++ public/images/academy/git-policy/6.svg | 178 +++ public/images/academy/git-policy/7.svg | 151 ++ public/images/academy/git-policy/8.svg | 149 ++ public/images/academy/git-policy/9.svg | 173 +++ resources/views/academy/git-policy.blade.php | 1286 +++++++++++++++++ .../components/academy-glossary.blade.php | 33 + routes/web.php | 2 + 15 files changed, 2849 insertions(+) create mode 100644 public/images/academy/git-policy/1.svg create mode 100644 public/images/academy/git-policy/10.svg create mode 100644 public/images/academy/git-policy/2.svg create mode 100644 public/images/academy/git-policy/3.svg create mode 100644 public/images/academy/git-policy/4.svg create mode 100644 public/images/academy/git-policy/5.svg create mode 100644 public/images/academy/git-policy/6.svg create mode 100644 public/images/academy/git-policy/7.svg create mode 100644 public/images/academy/git-policy/8.svg create mode 100644 public/images/academy/git-policy/9.svg create mode 100644 resources/views/academy/git-policy.blade.php diff --git a/.gitignore b/.gitignore index 8206959a..d317a974 100644 --- a/.gitignore +++ b/.gitignore @@ -159,3 +159,6 @@ package-lock.json # 검사 기준 이미지는 프로젝트 자산으로 추적 !public/img/inspection/ + +# 아카데미 SVG 일러스트는 프로젝트 자산으로 추적 +!public/images/academy/**/*.svg diff --git a/app/Http/Controllers/AcademyController.php b/app/Http/Controllers/AcademyController.php index cb1ea3bd..c020b6d6 100644 --- a/app/Http/Controllers/AcademyController.php +++ b/app/Http/Controllers/AcademyController.php @@ -79,4 +79,22 @@ public function envManagement(Request $request): View|Response return view('academy.env-management'); } + + public function gitPolicy(Request $request): View|Response + { + if ($request->header('HX-Request')) { + return response('', 200)->header('HX-Redirect', route('academy.git-policy')); + } + + return view('academy.git-policy'); + } + + public function nginxEncyclopedia(Request $request): View|Response + { + if ($request->header('HX-Request')) { + return response('', 200)->header('HX-Redirect', route('academy.nginx-encyclopedia')); + } + + return view('academy.nginx-encyclopedia'); + } } diff --git a/public/images/academy/git-policy/1.svg b/public/images/academy/git-policy/1.svg new file mode 100644 index 00000000..278c6a22 --- /dev/null +++ b/public/images/academy/git-policy/1.svg @@ -0,0 +1,114 @@ + + + + + + + + + + + + + + + + + + + + + 버전 관리의 필요성 + + + Before + + + + + + + + 견적서_최종.xlsx + + + + + + 견적서_진짜최종.xlsx + + + + + + 견적서_최종_v3.xlsx + + + + + + 견적서_최종_수정_Final.xlsx + + + + + + 견적서_최종_v3_진짜(2).xlsx + + + ? + ? + ? + + + + + ✕ + 혼란 + + + + + + + Git + + + After + + + + + + + + v1.0 - 견적서 초안 작성 + + + + + v1.1 - 금액 수정 + + + + + v1.2 - 할인 조건 추가 + + + + + v1.3 - 최종 확정 + + + + + v2.0 - 견적서 리뉴얼 + + + + ✓ + 체계적 관리 + + + 파일 복사 → Git 버전 관리로 전환 + \ No newline at end of file diff --git a/public/images/academy/git-policy/10.svg b/public/images/academy/git-policy/10.svg new file mode 100644 index 00000000..7c56bd4d --- /dev/null +++ b/public/images/academy/git-policy/10.svg @@ -0,0 +1,232 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + CI/CD 파이프라인 + 코드 변경부터 서버 배포까지 자동화된 흐름 + + + + + + + + + + + + + + + + + + + + + + + 1 + + + </> + + Code + 코드 작성 + + + + + + + + + + + + + 2 + + + + + + + + + Git Push + 코드 푸시 + + + + + + + + + + + + + 3 + + + + + + + + + + + + + + + Build + 빌드 + + + + + + + + + + + + + 4 + + + + + + Test + 자동 테스트 + + + + + + + + + + + + + 5 + + + + + + + + + + Deploy + 배포 + + + + + + + + + + + + + 6 + + + + + + + + + + Server + 운영 서버 + + + + + + + + + + + + + + + + + + + CI (Continuous Integration) + 코드 변경 시 자동으로 빌드하고 + 테스트를 실행하여 품질을 보장합니다 + + 자동화 + + + + + + CD (Continuous Deployment) + 테스트를 통과한 코드를 자동으로 + 서버에 배포하여 신속하게 반영합니다 + + 자동화 + + + + + + 개발자 + 코드 작성 + push + -> + CI 서버 + 빌드 + 테스트 + -> + CD + 자동 배포 + -> + 운영 서버 반영 + 수동 작업 최소화, 빠른 피드백, 안정적 배포 + + + + 코드 커밋부터 서버 배포까지 자동화된 컨베이어 벨트 + \ No newline at end of file diff --git a/public/images/academy/git-policy/2.svg b/public/images/academy/git-policy/2.svg new file mode 100644 index 00000000..a6ec24af --- /dev/null +++ b/public/images/academy/git-policy/2.svg @@ -0,0 +1,135 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Git 3단계 구조 + 코드가 저장소에 기록되기까지의 흐름 + + + + + + + + + + + + + + + + + + + Working + Directory + 작업 디렉토리 + + 코드를 수정하는 + 실제 작업 공간 + + + 1 + + + + + + + + git add + + + + + + + + + + + + + Staging + Area + 스테이징 영역 + 커밋할 변경사항을 + 준비하는 공간 + + + 2 + + + + + + + + git commit + + + + + + + + + + + + + + + + + Repository + 저장소 (.git) + 변경 이력이 + 영구 보관되는 곳 + + + 3 + + + + + 코드 수정 + → + git add + → + git commit + → + 이력 저장 완료 + + + + 수정 → 준비 → 확정, 3단계를 거쳐 코드가 기록됩니다 + \ No newline at end of file diff --git a/public/images/academy/git-policy/3.svg b/public/images/academy/git-policy/3.svg new file mode 100644 index 00000000..4c403f87 --- /dev/null +++ b/public/images/academy/git-policy/3.svg @@ -0,0 +1,138 @@ + + + + + + + + + + + + + + + + + + + + 원격 저장소 + 여러 개발자가 하나의 원격 저장소를 통해 협업합니다 + + + + + + + + + + + + + + + + + + + Origin (Remote) + + + + + + + + + + + + + + + + + + + + + + 개발자 A + + + + + + + + + + + + + + + + + 개발자 B + + + + + + + + + + + + + + + + + 개발자 C + + + + + + + + push + + + + + + pull + + + + + + push + + + + + + pull + + + + + + push + + + + + + pull + + + push로 업로드, pull로 다운로드 — 원격 저장소를 통한 협업 + \ No newline at end of file diff --git a/public/images/academy/git-policy/4.svg b/public/images/academy/git-policy/4.svg new file mode 100644 index 00000000..e75e20d3 --- /dev/null +++ b/public/images/academy/git-policy/4.svg @@ -0,0 +1,120 @@ + + + + + + + + + + + + + + + + + 브랜치 전략 + 브랜치를 활용한 안전한 병렬 개발 + + + + + + main (배포) + + develop (개발) + + feature/* (기능) + + hotfix/* (긴급수정) + + + + main + develop + feature/* + hotfix/* + + + + + + + + + + v1.0 + + v1.1 + + v2.0 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + feature/calendar + + + + hotfix/login-fix + + + merge + release + + + + + feature 작업 + => + develop 병합 + => + main 릴리즈 + | + hotfix는 main에서 직접 분기 + + \ No newline at end of file diff --git a/public/images/academy/git-policy/5.svg b/public/images/academy/git-policy/5.svg new file mode 100644 index 00000000..acb9b4a9 --- /dev/null +++ b/public/images/academy/git-policy/5.svg @@ -0,0 +1,117 @@ + + + + + + + + + + + + + + + + 커밋 메시지 + 좋은 커밋 메시지 vs 나쁜 커밋 메시지 + + + + + + + + + + + git log --oneline + + + + 좋은 커밋 메시지 + + + + + + ✓ + a3f8c21 + feat: [calendar] 달력 기능 개선 + + + + + + ✓ + b7e2d45 + fix: [auth] 세션 만료 오류 수정 + + + + + + ✓ + c9d1f83 + refactor: [user] 서비스 레이어 분리 + + + + + + ✓ + d2a5b67 + docs: [api] Swagger 문서 업데이트 + + + + + + + 나쁜 커밋 메시지 + + + + + + ✕ + e4f7a12 + 수정 + ← 무엇을 수정했는지 알 수 없음 + + + + + + ✕ + f8b3c56 + asdf + ← 의미 없는 텍스트 + + + + + + ✕ + a1c9e78 + 작업완료 + ← 어떤 작업인지 알 수 없음 + + + + + + ✕ + b2d4f90 + ㅋㅋ 이거 됨 + ← 비전문적, 정보 없음 + + + + + + 형식: + type: [scope] 작업내용 + 예) feat, fix, refactor, docs, chore, style, test + + \ No newline at end of file diff --git a/public/images/academy/git-policy/6.svg b/public/images/academy/git-policy/6.svg new file mode 100644 index 00000000..7312399b --- /dev/null +++ b/public/images/academy/git-policy/6.svg @@ -0,0 +1,178 @@ + + + + + + + + + + + + + + + + + + + + + + + + PR 워크플로우 + Pull Request를 통한 코드 리뷰 프로세스 + + + + + + + 1 + + + + + + + + + Branch + 브랜치 생성 + + + + + + + + + + + + + 2 + + + + + + + + + Commit + 코드 커밋 + + + + + + + + + + + + + 3 + + + + + + + + + PR + + PR 생성 + Pull Request + + + + + + + + + + + + + 4 + + + + + + + + ! + + Review + 코드 리뷰 + + + + + + + + + + + + + 5 + + + + + + + + + + Merge + 병합 완료 + + + + + + + $ git checkout -b feature/new + develop에서 새 브랜치를 + 생성하고 작업을 시작합니다 + + + + + + $ gh pr create + 변경사항을 설명하고 + 팀원에게 리뷰를 요청합니다 + + + + + + Approved + Merge + 리뷰 승인 후 develop에 + 병합하여 배포를 준비합니다 + + + + + + + + + + + + + + PR을 통해 코드 품질을 보장하고 팀 지식을 공유합니다 + \ No newline at end of file diff --git a/public/images/academy/git-policy/7.svg b/public/images/academy/git-policy/7.svg new file mode 100644 index 00000000..2d74ae1e --- /dev/null +++ b/public/images/academy/git-policy/7.svg @@ -0,0 +1,151 @@ + + + + + + + + + + + + + + + + + + + + + + + + + 충돌 해결 + 같은 파일을 동시에 수정했을 때 발생하는 충돌과 해결 방법 + + + 1. 분기 + + + + base + + + + + + + + + + branch-A + + + + + + + + + + branch-B + + + + + A: login.php 15행 수정 + B: login.php 15행 수정 + + + + 2. 충돌 발생 + + + + + + + + + + + + + + ! + + + CONFLICT + + + + + <<<<<<< branch-A + $user = Auth::user(); + ======= + $user = User::find($id); + >>>>>>> branch-B + + + + 3. 해결 완료 + + + + + + + + + + ✓ + + + + + + + + + 해결된 코드: + $user = Auth::user(); + // 팀 합의 후 A안 채택 + + + + + + 충돌 해결 절차 + + + + + 1 + 충돌 파일 확인 + + | + + + 2 + 마커 제거 + 코드 선택 + + | + + + 3 + git add + commit + + | + + + 4 + 해결 완료 + + 충돌은 자연스러운 현상입니다. 침착하게 해결하세요! + + + + 같은 부분을 동시에 수정하면 충돌이 발생하며, 수동으로 해결해야 합니다 + \ No newline at end of file diff --git a/public/images/academy/git-policy/8.svg b/public/images/academy/git-policy/8.svg new file mode 100644 index 00000000..7955ed76 --- /dev/null +++ b/public/images/academy/git-policy/8.svg @@ -0,0 +1,149 @@ + + + + + + + + + + + + + + + + + + + + + + + + SAM 멀티레포 구조 + 3개의 독립 저장소가 하나의 데이터베이스를 공유합니다 + + + + + + + + + + + + mng/ + 관리자 웹 + Laravel + HTMX + + + Controller + + Blade View + + + + + + + + + + + + api/ + API 서버 + Laravel + REST API + + Migration + + Model/API + + + + + + + + + + + + react/ + 프론트엔드 + Next.js + React + + Component + + Page/UI + + + + + + + Remote + sam-mng.git + + + + + + + Remote + sam-api.git + + + + + + + Remote + sam-react.git + + + + + + + + + + + + + + + MySQL 8.0 + 공유 데이터베이스 + + + + + + + + + + + + + DB 관리 주체 + + + API 경유 + + + + + 핵심 규칙: + 마이그레이션은 + api/ + 에서만 관리 + | + 각 폴더는 + 독립 Git 저장소 + + \ No newline at end of file diff --git a/public/images/academy/git-policy/9.svg b/public/images/academy/git-policy/9.svg new file mode 100644 index 00000000..65240caa --- /dev/null +++ b/public/images/academy/git-policy/9.svg @@ -0,0 +1,173 @@ + + + + + + + + + + + + + + + + + + + + + + + + .gitignore 보안 + 민감한 파일과 불필요한 파일을 Git 추적에서 제외합니다 + + + 모든 파일 + + + + + + .env + 비밀키 + + + + + + + node_modules/ + + + + + + + .DS_Store + + + + + + + vendor/ + + + + + + + app.php + + + + + + + routes.php + + + + + + + README.md + + + + + + + + + + + + + + + + + + + + + + .gitignore + + + + + + + + + + + + ✕ + + + + ✕ + + + + ✕ + + + + + + + + + + + + + + Git 저장소 + + + + + + ✓ + app.php + + + + ✓ + routes.php + + + + ✓ + README.md + + + + + + + ✕ + .env + + + + ✕ + node_modules/ + + + + + + + # .gitignore + .env node_modules/ vendor/ .DS_Store *.log storage/*.key + + \ No newline at end of file diff --git a/resources/views/academy/git-policy.blade.php b/resources/views/academy/git-policy.blade.php new file mode 100644 index 00000000..afa4881d --- /dev/null +++ b/resources/views/academy/git-policy.blade.php @@ -0,0 +1,1286 @@ +@extends('layouts.app') + +@section('title', 'Git 정책 백과사전') + +@push('styles') + +@endpush + +@section('content') +
+ + {{-- ============================================================ --}} + {{-- 히어로 배너 --}} + {{-- ============================================================ --}} +
+
+
+
+ 아카데미 + + Git 정책 +
+

Git 정책 백과사전

+

버전 관리의 기초부터 SAM 프로젝트 Git 정책까지 — 비개발자도 이해하는 Git 가이드

+
+
+
+ 버전 관리의 필요성 +
+
+
+
+ +
+ {{-- ============================================================ --}} + {{-- 좌측 고정 목차 (TOC) --}} + {{-- ============================================================ --}} + + + {{-- ============================================================ --}} + {{-- 우측 콘텐츠 --}} + {{-- ============================================================ --}} +
+ + {{-- 모바일 목차 --}} +
+
+ + + 목차 보기 + + +
+
+ + {{-- ============================================================ --}} + {{-- 1. 버전 관리란? --}} + {{-- ============================================================ --}} +
+
+

+ 1 + 버전 관리란? +

+ +
+

+ + 파일 혼돈의 시대 + ?버전 관리 시스템(VCS)이 없던 시절, 대부분의 팀은 파일명에 날짜나 버전 번호를 붙여 관리했다. 이 방식은 파일이 늘어날수록 어떤 것이 최신인지 알 수 없게 된다. +

+
+

비유: 견적서_최종_진짜최종.xlsx의 악몽

+

+ 엑셀 파일을 수정할 때마다 "견적서_수정.xlsx", "견적서_최종.xlsx", + "견적서_최종_수정.xlsx", "견적서_진짜최종_v3.xlsx"... + 이렇게 파일이 불어난 경험이 있을 것이다. 어느 것이 진짜 최종인지 아무도 모른다. + Git은 이 악몽을 완전히 해결한다. +

+
+
+

+ 버전 관리란 파일의 변경 이력을 체계적으로 기록하고 관리하는 것이다. + 누가, 언제, 무엇을, 왜 변경했는지를 자동으로 추적하며, + 필요하면 과거의 어떤 시점으로든 되돌릴 수 있다. +

+
+
+ +
+

+ + Git이 해결하는 3가지 문제 +

+
+
+
+ +
+

1. 이력 추적

+

모든 변경이 기록된다.
누가, 언제, 왜 바꿨는지
언제든 확인 가능.

+
+
+
+ +
+

2. 동시 작업

+

여러 사람이 같은 파일을
동시에 수정해도
안전하게 합칠 수 있다.

+
+
+
+ +
+

3. 되돌리기

+

실수해도 과거 시점으로
자유롭게 복원 가능.
파일이 깨질 걱정 없음.

+
+
+
+

+ Git vs 클라우드 동기화: + Google Drive나 OneDrive도 파일 이력을 보여주지만, Git과는 근본적으로 다르다. + 클라우드는 자동 저장이지만, Git은 의미 있는 단위로 직접 기록한다. + "견적 금액 10% 인상 반영"처럼 변경 이유까지 남길 수 있다. +

+
+
+ 버전 관리의 필요성 +
+

버전 관리 전후 비교 — 파일명 혼돈 vs Git 타임라인

+
+
+
+ + {{-- ============================================================ --}} + {{-- 2. Git 기초 개념 --}} + {{-- ============================================================ --}} +
+
+

+ 2 + Git 기초 개념 +

+ +
+

+ + Git의 3단계 구조 + ?Git은 파일을 3개 영역으로 관리한다. Working Directory(작업 공간), Staging Area(준비 영역), Repository(저장소). 각 영역의 역할을 이해하면 Git의 핵심을 파악한 것이다. +

+
+

비유: 책상 → 봉투 → 캐비닛

+

+ Working Directory는 작업 중인 책상이다. 파일을 자유롭게 수정한다. + Staging Area는 보낼 서류를 담는 봉투다. git add로 봉투에 넣는다. + Repository는 최종 보관하는 캐비닛이다. git commit으로 캐비닛에 저장한다. +

+
+
# 1. 책상에서 파일 수정 (Working Directory) +파일을 수정한다 + +# 2. 봉투에 넣기 (Staging Area) +git add 파일이름.php + +# 3. 캐비닛에 보관 (Repository) +git commit -m "feat: [order] 주문 기능 추가"
+
+ Git 3단계 구조 +
+

Git 3단계 — Working Directory → Staging → Repository

+
+ +
+

+ + 커밋과 해시 +

+
+

+ Commit은 특정 시점의 스냅샷이다. + 각 커밋에는 커밋 해시라는 고유 ID가 자동 부여된다. + 예: a1b2c3d. + 이 해시로 어떤 커밋이든 정확히 찾아갈 수 있다. +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
명령어역할비유
git status현재 상태 확인책상 위 정리 상태 확인
git add스테이징에 추가서류를 봉투에 넣기
git commit변경 기록 저장봉투를 캐비닛에 보관
git log커밋 이력 조회캐비닛 보관 목록 열람
git diff변경 내용 비교수정 전후 대조
+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 3. 원격 저장소와 클론 --}} + {{-- ============================================================ --}} +
+
+

+ 3 + 원격 저장소와 클론 +

+ +
+

+ + Push와 Pull + ?원격 저장소(Remote)는 팀원 모두가 접근할 수 있는 중앙 서버에 있는 저장소다. GitHub, GitLab, Gitea 등이 원격 저장소 서비스를 제공한다. +

+
+

비유: 팀 공용 캐비닛

+

+ 로컬 저장소가 내 책상의 캐비닛이라면, 원격 저장소는 팀 공용 캐비닛이다. + Push는 내 서류를 공용 캐비닛에 올리는 것이고, + Pull은 다른 사람이 올린 서류를 내 책상으로 가져오는 것이다. +

+
+
# 내 작업을 원격에 업로드 +git push origin develop + +# 원격의 최신 변경을 가져오기 +git pull origin develop
+
+ 원격 저장소 +
+

원격 저장소 — 로컬 ↔ 중앙 서버 동기화

+
+ +
+

+ + Clone과 Origin +

+
+

+ Clone은 원격 저장소를 통째로 내 PC에 복사하는 것이다. + 프로젝트에 처음 참여할 때 한 번만 실행한다. + Clone하면 원격 저장소에 자동으로 Origin이라는 이름이 붙는다. +

+
+
# 프로젝트 처음 참여 시 — 전체 복사 +git clone https://gitea.example.com/sam/mng.git + +# 이후에는 pull로 최신 변경만 동기화 +git pull
+
+

+ SAM의 원격 저장소: + SAM은 자체 호스팅 Gitea 서버를 사용한다. + GitHub처럼 웹 브라우저에서 코드를 보고, PR을 만들고, 이슈를 관리할 수 있다. +

+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 4. 브랜치 --}} + {{-- ============================================================ --}} +
+
+

+ 4 + 브랜치 +

+ +
+

+ + 브랜치란? + ?브랜치(Branch)는 '가지'라는 뜻이다. 나무 줄기(main)에서 가지가 뻗어나가듯, 메인 코드에서 분기하여 독립적으로 작업한 뒤 다시 합친다. +

+
+

비유: 생산라인 분기점

+

+ 공장의 메인 생산라인(main)에서 시험 생산라인을 따로 만들어 새 제품을 테스트하는 것이다. + 테스트가 성공하면 메인 라인에 합류시키고(merge), 실패하면 시험 라인만 폐쇄하면 된다. + 메인 라인은 영향 없이 계속 가동된다. +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
브랜치역할예시
main운영 서버에 배포된 안정 코드실제 서비스 중인 코드
develop개발 통합 브랜치다음 릴리즈 준비 코드
feature/*새 기능 개발feature/file-upload
hotfix/*긴급 버그 수정hotfix/login-session-bug
+
+
+ 브랜치 전략 +
+

브랜치 전략 — main / develop / feature / hotfix

+
+ +
+

+ + 브랜치 만들기와 머지 +

+
# 새 기능 브랜치 만들기 +git checkout -b feature/file-upload + +# 작업 후 커밋 +git add . +git commit -m "feat: [file] 파일 업로드 기능 추가" + +# develop 브랜치로 돌아와서 머지 +git checkout develop +git merge feature/file-upload
+
+

+ Merge는 분기된 작업을 다시 하나로 합치는 것이다. + feature 브랜치에서 개발을 완료하면 develop에 merge하고, + develop이 안정화되면 main에 merge한다. +

+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 5. 커밋 메시지 작성법 --}} + {{-- ============================================================ --}} +
+
+

+ 5 + 커밋 메시지 작성법 +

+ +
+

+ + SAM 커밋 메시지 컨벤션 + ?커밋 메시지 컨벤션이란 팀 전체가 동일한 형식으로 커밋 메시지를 작성하는 약속이다. 통일된 형식은 이력 검색과 코드 리뷰를 빠르게 만든다. +

+
+

비유: 작업 일지

+

+ 커밋 메시지는 공장의 작업 일지다. "작업함"이라고 적으면 나중에 아무도 내용을 알 수 없다. + "셔터 A라인 모터 교체 완료 — 소음 문제 해결"처럼 구체적으로 적어야 한다. +

+
+
+

+ SAM 프로젝트 커밋 메시지 형식: +

+
type: [scope] 작업 내용 + +- 세부 항목 (선택) +- 세부 항목 2
+
+
+ 커밋 메시지 +
+

좋은 커밋 메시지 vs 나쁜 커밋 메시지

+
+ +
+

+ + 7가지 커밋 타입 +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
타입설명예시
feat새로운 기능 추가feat: [file] 파일 업로드 기능 추가
fix버그 수정fix: [auth] 세션 만료 오류 수정
refactor코드 구조 개선refactor: [user] 서비스 메서드 분리
docs문서 변경docs: API 문서 업데이트
chore설정/빌드 변경chore: composer 패키지 업데이트
style코드 스타일 수정style: Pint 포맷팅 적용
test테스트 추가/수정test: Product API 테스트 추가
+
+
+
+

fix = 깨진 것을 고친다

+

버그, 오류, 잘못된 결과

+
+
+

feat = 없던 것을 만든다

+

신규 기능, 기능 확장

+
+
+

refactor = 같은 것을 더 좋게

+

구조 개선, 중복 제거

+
+
+
+

+ 커밋 빈도: + "논리적 단위"로 커밋한다. 파일 하나 수정마다 커밋하는 것은 너무 잦고, + 몇 시간 작업을 한 번에 커밋하면 되돌리기 어렵다. + 하나의 의미 있는 변경이 완성되면 커밋한다. +

+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 6. 협업 워크플로우 --}} + {{-- ============================================================ --}} +
+
+

+ 6 + 협업 워크플로우 +

+ +
+

+ + Pull Request와 코드 리뷰 + ?Pull Request(PR)란 내가 만든 변경 사항을 팀 브랜치에 합쳐달라고 요청하는 것이다. 다른 개발자가 코드를 검토(리뷰)한 후 승인하면 머지된다. +

+
+

비유: 품질검사 신청서

+

+ Pull Request는 품질검사 신청서다. + 생산라인에서 만든 제품을 바로 출하하지 않고, 품질검사 부서에 "검사해주세요"라고 신청한다. + 검사관(리뷰어)이 확인하고 "합격"을 주면 출하(merge)된다. +

+
+
+ PR 워크플로우 +
+

PR 워크플로우 — 브랜치 → 커밋 → PR → 리뷰 → 머지

+
+ +
+

+ + 팀 워크플로우 +

+
+

+ SAM 프로젝트의 일반적인 작업 흐름: +

+
+
+ 1 + develop에서 feature 브랜치를 만든다 +
+
+ 2 + 기능을 개발하고 커밋한다 +
+
+ 3 + Pull Request를 생성하여 코드 리뷰를 요청한다 +
+
+ 4 + 리뷰 승인 후 develop에 머지한다 +
+
+ 5 + develop이 안정되면 main에 머지하고 배포한다 +
+
+
+
# 1. 브랜치 생성 +git checkout -b feature/file-storage-system + +# 2. 작업 및 커밋 +git add . +git commit -m "feat: [file] 파일 저장 시스템 구현" + +# 3. 원격에 푸시 후 PR 생성 +git push origin feature/file-storage-system +# → Gitea에서 PR 생성
+
+
+
+ + {{-- ============================================================ --}} + {{-- 7. 충돌 해결 --}} + {{-- ============================================================ --}} +
+
+

+ 7 + 충돌 해결 +

+ +
+

+ + 충돌이란? + ?충돌(Conflict)은 두 사람이 같은 파일의 같은 줄을 다르게 수정했을 때 발생한다. Git이 어떤 변경을 채택해야 할지 모르기 때문에 사람이 직접 선택해야 한다. +

+
+

비유: 공동 엑셀 편집

+

+ A씨와 B씨가 같은 엑셀 파일의 같은 셀을 동시에 다른 값으로 수정한 상황이다. + A씨는 "100,000"으로, B씨는 "150,000"으로 바꿨다. 누구 것을 쓸지는 사람이 판단해야 한다. +

+
+
// 충돌 마커 — Git이 파일에 표시해주는 형태 +<<<<<<< HEAD +$price = 100000; // 내가 수정한 내용 +======= +$price = 150000; // 상대방이 수정한 내용 +>>>>>>> feature/price-update
+
+ 충돌 해결 +
+

머지 충돌 — 두 브랜치가 같은 부분을 수정했을 때

+
+ +
+

+ + 충돌 해결 3단계 +

+
+
+

1단계: 충돌 파일 확인

+

git status로 "both modified" 표시된 파일을 찾는다.

+
+
+

2단계: 내용 선택

+

에디터에서 <<<<<<<, =======, >>>>>>> 마커를 찾고 원하는 내용만 남긴다.

+
+
+

3단계: 커밋

+

git add로 해결된 파일을 추가하고 git commit으로 머지를 완료한다.

+
+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 8. SAM 프로젝트 Git 정책 --}} + {{-- ============================================================ --}} +
+
+

+ 8 + SAM 프로젝트 Git 정책 +

+ +
+

+ + 3개 독립 저장소 + ?SAM은 멀티레포 전략을 사용한다. 하나의 거대한 저장소(모노레포) 대신, 역할별로 분리된 3개 저장소를 운영하여 각 팀이 독립적으로 작업할 수 있다. +

+
+

비유: 공장 3개 부서

+

+ SAM의 3개 저장소는 공장의 3개 독립 부서와 같다. + MNG(관리부)는 관리자 화면, API(생산부)는 데이터 처리, + React(영업부)는 고객용 화면을 담당한다. + 각 부서는 독립적으로 작업하지만, 하나의 공장(DB)을 공유한다. +

+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
저장소경로역할
mng/home/aweso/sam/mng관리자 웹 (Laravel + Blade)
api/home/aweso/sam/apiAPI 서버 (Laravel)
react/home/aweso/sam/react프론트엔드 (Next.js)
+
+
+ SAM 멀티레포 +
+

SAM 멀티레포 구조 — mng / api / react

+
# 각 저장소에서 개별 커밋 (중요!) +cd /home/aweso/sam/mng +git add . && git commit -m "feat: [order] 주문 화면 추가" + +cd /home/aweso/sam/api +git add . && git commit -m "feat: [order] 주문 API 추가"
+
+ +
+

+ + 푸시 정책과 Pre-commit +

+
+
+

푸시 정책

+
    +
  • - main/master에서 직접 작업 금지
    • +
  • - develop 브랜치를 기본으로 사용
    • +
  • - 사용자(팀장)가 수동으로 push
    • +
  • - Claude는 커밋까지만 수행
    • +
+
+
+

Pre-commit Hook

+
    +
  • - 커밋 전 Pint 자동 실행
    • +
  • - 코드 포맷팅 자동 정리
    • +
  • - Claude 서명 자동 제거
    • +
  • - 포맷 오류 시 커밋 차단
    • +
+
+
+
+

+ 커밋 전 체크리스트: + ./vendor/bin/pint 실행 → + git diff로 변경 검토 → + 불필요 파일(.env 등) 제외 → + git add → + git commit +

+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 9. .gitignore와 보안 --}} + {{-- ============================================================ --}} +
+
+

+ 9 + .gitignore와 보안 +

+ +
+

+ + .gitignore란? + ?.gitignore는 Git이 추적하지 않을 파일 목록이다. 여기에 등록된 파일은 git add 해도 스테이징되지 않는다. 비밀번호, 대용량 파일, OS 임시 파일 등을 제외할 때 사용한다. +

+
+

비유: 캐비닛 반입금지 목록

+

+ .gitignore는 캐비닛(저장소)에 넣으면 안 되는 물건 목록이다. + 비밀문서(비밀번호), 임시 메모(로그 파일), 개인 물건(IDE 설정) 등은 + 공용 캐비닛에 넣지 않는다. +

+
+
# SAM .gitignore 주요 항목 + +# 환경 설정 (비밀번호 포함) +.env +.env.* +!.env.example # 양식만 추적 + +# 외부 패키지 (용량 큼) +/vendor/ +/node_modules/ + +# IDE 설정 (개인별 다름) +.idea/ +.vscode/ +.cursor/ + +# 로그, 백업, 바이너리 +*.log +*.sql +*.zip
+
+ .gitignore 보안 +
+

.gitignore — 민감 파일을 저장소에서 차단하는 방패

+
+ +
+

+ + .env 파일 보안 +

+
+

절대 금지: .env 파일을 Git에 커밋

+

+ .env 파일에는 데이터베이스 비밀번호, API 키, 암호화 키가 들어 있다. + 이 파일이 Git에 올라가면 모든 이력에 비밀번호가 남게 되어 + 삭제해도 이력에서 복구할 수 있다. 한 번 유출되면 모든 비밀번호를 교체해야 한다. +

+
+
+
+

Git에 올리면 안 되는 파일

+

.env, credentials.json, *.key
storage/secrets/, auth.json

+
+
+

Git에 올려야 하는 파일

+

.env.example (양식만, 값은 비움)
.gitignore, .gitattributes

+
+
+
+
+
+ + {{-- ============================================================ --}} + {{-- 10. 배포와 CI/CD --}} + {{-- ============================================================ --}} +
+
+

+ 10 + 배포와 CI/CD +

+ +
+

+ + Git 기반 배포 + ?CI/CD는 코드 변경 시 자동으로 빌드→테스트→배포하는 자동화 파이프라인이다. CI(Continuous Integration)는 코드 통합, CD(Continuous Deployment)는 자동 배포를 뜻한다. +

+
+

비유: 자동화 컨베이어 벨트

+

+ CI/CD는 공장의 자동화 컨베이어 벨트다. + 원재료(코드)를 올려놓으면 가공(빌드) → 품질검사(테스트) → 포장(패키징) → 출하(배포)가 + 자동으로 진행된다. 사람이 각 단계를 직접 실행할 필요가 없다. +

+
+
+

+ SAM의 배포 흐름: +

+
+
+ 1 + 개발자가 코드 작성 후 git commit +
+
+ 2 + 팀장이 git push로 원격 저장소에 업로드 +
+
+ 3 + 서버에서 git pull로 최신 코드 받기 +
+
+ 4 + composer install → migrate → config:clear +
+
+ 5 + 서비스 정상 동작 확인 +
+
+
+
+ CI/CD 파이프라인 +
+

CI/CD 파이프라인 — 코드에서 배포까지의 자동화 흐름

+
+ +
+

+ + 롤백: revert vs reset +

+
+

+ 배포 후 문제가 발생하면 이전 버전으로 되돌려야 한다. Git에서는 두 가지 방법이 있다. +

+
+
+
+

Revert (권장)

+
    +
  • - 되돌리는 새 커밋을 생성
    • +
  • - 이력이 보존되어 안전
    • +
  • - 팀 작업에 영향 없음
    • +
  • - git revert <해시>
    • +
+
+
+

Reset (주의)

+
    +
  • - 커밋 이력 자체를 삭제
    • +
  • - 되돌린 기록이 남지 않음
    • +
  • - 팀 작업에 혼란 가능
    • +
  • - 로컬에서만 사용 권장
    • +
+
+
+
# 안전한 롤백 — revert (권장) +git revert a1b2c3d # 해당 커밋을 되돌리는 새 커밋 생성 + +# 위험한 롤백 — reset (주의!) +git reset --soft HEAD~1 # 직전 커밋 취소 (변경은 유지) +git reset --hard HEAD~1 # 직전 커밋 + 변경 모두 삭제 (위험!)
+
+

+ SAM 배포 참고: + SAM에서는 React(Next.js) 빌드를 서버에서 실행하지 않는다. + 서버 스펙(2코어, 3.8GB RAM)으로는 빌드 시 메모리 부족이 발생하므로, + 반드시 로컬에서 빌드 후 결과물만 배포한다. +

+
+
+
+
+ +
+
+
+ + +
+ + +
+ + + + + +@include('components.academy-glossary', ['domain' => 'git-policy']) +@endsection diff --git a/resources/views/components/academy-glossary.blade.php b/resources/views/components/academy-glossary.blade.php index a0203ac4..8911a2e0 100644 --- a/resources/views/components/academy-glossary.blade.php +++ b/resources/views/components/academy-glossary.blade.php @@ -317,6 +317,39 @@ "sudo": "일반 사용자가 관리자(root) 권한으로 명령을 실행할 수 있게 하는 명령어.", "systemctl": "systemd 서비스를 시작·중지·재시작·상태확인하는 관리 명령어." }; +@elseif($domain === 'git-policy') +window.__GLOSSARY_DATA['git-policy'] = { + "Git": "소스 코드 버전 관리 시스템. 파일의 변경 이력을 추적하고 여러 사람이 동시에 작업할 수 있게 한다.", + "버전 관리": "파일의 변경 이력을 체계적으로 기록·관리하는 것. 언제, 누가, 무엇을 바꿨는지 추적할 수 있다.", + "Repository": "저장소. Git이 파일과 변경 이력을 보관하는 공간. 프로젝트 폴더 안의 .git 폴더가 실체이다.", + "Commit": "변경 사항을 저장소에 기록하는 행위. 작업 일지의 한 줄에 해당하며, 고유한 해시값을 가진다.", + "Branch": "독립적인 작업 공간. 메인 코드에 영향을 주지 않고 새 기능을 개발할 수 있는 분기점.", + "Merge": "두 브랜치의 변경 사항을 하나로 합치는 것. 분리된 작업을 다시 통합하는 과정.", + "Pull Request": "코드 변경을 본 브랜치에 합쳐달라는 요청. 코드 리뷰를 거친 뒤 승인되면 머지된다.", + "Clone": "원격 저장소의 전체 내용을 로컬에 복사하는 것. 프로젝트에 처음 참여할 때 사용한다.", + "Push": "로컬 커밋을 원격 저장소에 업로드하는 것. 내 작업을 팀 공유 저장소에 올리는 행위.", + "Pull": "원격 저장소의 최신 변경 사항을 로컬로 가져오는 것. 다른 사람의 작업을 내 PC에 동기화한다.", + "Staging Area": "커밋할 파일을 미리 모아두는 중간 영역. git add로 파일을 이곳에 올린다.", + "Working Directory": "실제 파일을 편집하는 작업 공간. 프로젝트 폴더 그 자체를 의미한다.", + "Conflict": "같은 파일의 같은 부분을 두 사람이 다르게 수정했을 때 발생하는 충돌. 수동으로 해결해야 한다.", + "Revert": "특정 커밋의 변경 사항을 되돌리는 새 커밋을 만드는 것. 이력이 보존되어 안전하다.", + "Reset": "커밋 이력 자체를 되돌리는 것. 이력이 사라지므로 주의가 필요하다.", + ".gitignore": "Git이 추적하지 않을 파일 목록을 정의하는 파일. .env, node_modules 등을 제외할 때 사용한다.", + "HEAD": "현재 체크아웃된 브랜치의 최신 커밋을 가리키는 포인터. '지금 내가 보고 있는 위치'를 뜻한다.", + "Origin": "원격 저장소의 기본 이름. git clone 시 자동으로 origin이라는 이름이 붙는다.", + "develop 브랜치": "개발 통합 브랜치. 기능 개발이 완료되면 여기에 합치고, 안정화 후 main에 반영한다.", + "feature 브랜치": "새 기능을 개발하는 임시 브랜치. feature/기능명 형식으로 이름을 짓는다.", + "hotfix 브랜치": "운영 중 긴급 버그를 수정하는 브랜치. main에서 분기하여 빠르게 수정 후 바로 병합한다.", + "커밋 해시": "각 커밋에 부여되는 40자리 고유 식별자. SHA-1 알고리즘으로 생성되며 앞 7자리만 써도 된다.", + "git log": "커밋 이력을 시간 순으로 보여주는 명령어. 누가 언제 무엇을 바꿨는지 확인할 수 있다.", + "git status": "현재 작업 디렉토리의 상태를 보여주는 명령어. 수정·추가·삭제된 파일을 확인한다.", + "git diff": "파일의 변경 내용을 줄 단위로 비교하는 명령어. 커밋 전 변경 사항을 검토할 때 사용한다.", + "Pre-commit Hook": "커밋 실행 직전에 자동으로 실행되는 스크립트. 코드 포맷팅, 린트 검사 등을 자동화한다.", + "CI/CD": "지속적 통합/지속적 배포. 코드 변경 시 자동으로 빌드·테스트·배포하는 자동화 파이프라인.", + "Gitea": "경량 자체 호스팅 Git 서비스. GitHub와 유사하지만 자체 서버에서 운영한다. SAM이 사용 중.", + "멀티레포": "하나의 프로젝트를 여러 독립 저장소로 나누어 관리하는 전략. SAM은 mng/api/react 3개로 운영.", + "Pint": "Laravel 공식 코드 포맷터. PHP 코드 스타일을 자동으로 정리해주는 도구. Pre-commit에서 자동 실행." +}; @elseif($domain === 'env-management') window.__GLOSSARY_DATA['env-management'] = { ".env": "환경 변수를 저장하는 설정 파일. DB 접속 정보, API 키 등 환경마다 달라지는 값을 관리한다.", diff --git a/routes/web.php b/routes/web.php index 76d6f644..43ec461a 100644 --- a/routes/web.php +++ b/routes/web.php @@ -1469,6 +1469,8 @@ Route::get('/web-basics', [\App\Http\Controllers\AcademyController::class, 'webBasics'])->name('web-basics'); Route::get('/backend-dev', [\App\Http\Controllers\AcademyController::class, 'backendDev'])->name('backend-dev'); Route::get('/env-management', [\App\Http\Controllers\AcademyController::class, 'envManagement'])->name('env-management'); + Route::get('/git-policy', [\App\Http\Controllers\AcademyController::class, 'gitPolicy'])->name('git-policy'); + Route::get('/nginx-encyclopedia', [\App\Http\Controllers\AcademyController::class, 'nginxEncyclopedia'])->name('nginx-encyclopedia'); }); // SAM E-Sign - 인증 필요