From 44b4cc26518c14a34a436def9ecdd620eeb6311a Mon Sep 17 00:00:00 2001 From: iamroseyoung <16571795+iamroseyoung@users.noreply.github.com> Date: Wed, 2 Sep 2026 11:06:37 +0900 Subject: [PATCH 1/3] Create contribution-start.md --- contribution-start.md | 303 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 insertions(+) create mode 100644 contribution-start.md diff --git a/contribution-start.md b/contribution-start.md new file mode 100644 index 0000000..e3fe96c --- /dev/null +++ b/contribution-start.md @@ -0,0 +1,303 @@ +### 전자정부 표준프레임워크 GitHub Contribution 시작 가이드 + +Git을 처음 사용해도 괜찮아요. +이번 목표는 Git 명령어를 모두 외우는 것이 아닙니다. 직접 문서를 수정하고 **표준프레임워크에 Pull Request(PR)를 보내는 것**이 목표입니다. + + +## 전체 흐름 +1. GitHub 계정 만들기 +2. 개발 환경 준비하기 (VS Code + Git + Codex) +3. Git 사용자 정보 설정하기 +4. 대상 Repository Fork 하기 +5. 내 PC에 Clone 하기 +6. AI를 활용해 Contribution 대상 찾기 +7. 문서 수정하기 + * 기존 파일 수정 + * 새로운 파일 만들기 +8. 변경사항 확인하기 +9. Commit 하기 +10. 내 GitHub Repository로 Push 하기 +11. Pull Request 보내기 → 표준프레임워크 원본 Repository + +--- + +# 기본 개념 + +### GitHub이란? + +GitHub은 여러 사람이 소스코드와 문서를 함께 관리하고 협업하는 공간입니다. + +이번에는 표준프레임워크 문서를 수정하고, 그 결과를 GitHub를 통해 기여해 봅니다. + +--- + +## 1. GitHub 계정 만들기 + +먼저 GitHub에서 계정을 만들고 로그인합니다. + +가입이 끝나면 나만의 GitHub 주소가 생깁니다. + +```text +https://github.com/내아이디 +``` + +예를 들면 다음과 같습니다. + +```text +https://github.com/example-user +``` + +이후 표준프레임워크 Repository를 Fork하면 내 GitHub 계정 아래에 Repository 복사본이 만들어집니다. + +--- + +## 2. 개발 환경 준비하기 + +이번 실습에서는 세 가지 도구를 사용합니다. + +* Git +* VS Code +* Codex + +### 준비할 것 + +* Git 설치 +* VS Code 설치 +* Codex 설치 및 로그인 + +준비가 끝났다면 이제 Contribution을 시작할 수 있습니다. + +--- + +## 3. Git 사용자 정보 설정하기 + +Git은 Commit을 만들 때 누가 작업했는지 함께 기록합니다. + +VS Code에서 터미널을 열고 아래 명령어를 실행합니다. + +```bash +git config --global user.name "본인 이름" +git config --global user.email "본인 이메일" +``` + +잘 설정됐는지 확인하려면 다음 명령어를 실행합니다. + +```bash +git config --global --list +``` + +--- + +## 4. Repository Fork 하기 + +이번에 Contribution할 Repository입니다. + +https://github.com/eGovFramework/egovframe-docs + +Repository 오른쪽 위에 있는 **Fork** 버튼을 클릭합니다. + +Fork는 간단히 말하면 **원본 Repository를 내 GitHub 계정으로 복사하는 것**입니다. + +```text +원본 Repository +eGovFramework/egovframe-docs + ↓ Fork +내 GitHub Repository +내아이디/egovframe-docs +``` + +원본을 바로 수정하는 것이 아니라, 내 Repository에서 먼저 작업한다고 생각하면 됩니다. + +--- + +## 5. 내 PC로 Clone 하기 + +이제 GitHub에 있는 내 Repository를 내 PC로 가져옵니다. + +Fork한 Repository에서 주소를 복사한 후 터미널에서 실행합니다. + +```bash +git clone https://github.com/내아이디/egovframe-docs.git +``` + +폴더로 이동합니다. + +```bash +cd egovframe-docs +``` + +그리고 VS Code로 엽니다. + +```bash +code . +``` + +이제 내 PC에서 문서를 수정할 준비가 끝났습니다. + +--- + +## 6. AI와 함께 Contribution 대상 찾기 + +여기서 이런 고민이 생길 수 있습니다. + +> "그래서 어떤 문서를 수정하지?" + +이럴 때 AI에게 물어보면 됩니다. + +Codex에게 다음 프롬프트를 입력해 보세요. + +```text +기존 개발가이드와 GitHub Repository의 문서를 비교하여 +아직 Markdown으로 전환되지 않았거나 현행화가 필요한 +공통컴포넌트 가이드를 찾고, +실제 Pull Request로 기여하기 좋은 대상 5개를 +우선순위와 함께 추천해주세요. + +대상 Repository: +https://github.com/eGovFramework/egovframe-docs + +기존 개발가이드: +https://www.egovframe.go.kr/wiki/doku.php?id=egovframework:공통컴포넌트가이드 +``` + +AI가 추천한 대상 중 하나를 골라 작업을 시작합니다. + +처음이라면 너무 큰 작업보다는 **작은 문서 하나를 제대로 완성하는 것**을 추천합니다. + +--- + +## 7. 문서 수정하기 + +바로 "수정해줘"라고 하기보다는 먼저 무엇을 수정할지 확인해 보는 것이 좋습니다. + +먼저 AI에게 다음 내용을 확인합니다. + +1. 어떤 파일을 수정해야 하는지 +2. 왜 수정이 필요한지 +3. 무엇을 변경할 것인지 +4. 작업 범위가 어디까지인지 + +확인한 후 AI와 함께 문서를 수정합니다. + +작업 방법은 크게 두 가지입니다. + +* 기존 Markdown 파일 수정하기 +* 새로운 Markdown 파일 만들기 + +> AI가 작성한 내용도 한 번은 직접 읽고 확인하는 것이 좋습니다. + +--- + +## 8. 변경사항 확인하기 + +문서를 수정했다면 무엇이 바뀌었는지 확인합니다. + +```bash +git status +``` + +조금 더 자세한 내용을 보고 싶다면 다음 명령어를 사용합니다. + +```bash +git diff +``` + +```text +파일 수정 + ↓ +git status로 확인 + ↓ +git diff로 변경 내용 확인 +``` + +--- + +## 9. Commit 하기 + +수정한 파일을 먼저 Git에 추가합니다. + +```bash +git add . +``` + +그리고 작업 내용을 하나의 기록으로 저장합니다. + +```bash +git commit -m "docs: update common component guide" +``` + +Commit 메시지는 어렵게 생각하지 않아도 됩니다. + +**"내가 무엇을 수정했는지 짧게 설명한다"** 정도로 생각하면 됩니다. + +--- + +## 10. 내 GitHub Repository로 Push 하기 + +내 PC에서 작업한 내용을 GitHub에 올립니다. + +```bash +git push +``` + +```text +내 PC + ↓ git push +내 GitHub Repository +``` + +--- + +## 11. Pull Request 보내기 + +이제 마지막 단계입니다. + +GitHub에서 **Compare & Pull Request** 버튼을 클릭합니다. + +```text +내 Repository +내아이디/egovframe-docs + ↓ Pull Request +원본 Repository +eGovFramework/egovframe-docs +``` + +어떤 내용을 수정했는지 간단하게 작성하고 Pull Request를 생성합니다. + +그리고 끝! 🎉 + +--- + +# 전체 흐름 다시 보기 + +```text +GitHub 계정 만들기 + ↓ +VS Code + Git + Codex 준비 + ↓ +Git 사용자 정보 설정 + ↓ +Repository Fork + ↓ +내 PC로 Clone + ↓ +AI로 Contribution 대상 찾기 + ↓ +문서 수정 + ↓ +변경사항 확인 + ↓ +git add + ↓ +git commit + ↓ +git push + ↓ +Pull Request + ↓ +🎉 첫 번째 Contribution 완료! +``` + +> Git을 완벽하게 이해한 다음 시작할 필요는 없습니다. +> 직접 한 번 Fork하고, 수정하고, Commit하고, Pull Request를 보내보면 Git과 GitHub가 훨씬 쉽게 이해됩니다. + From bdd0fec38c5e6959742362b56acab4d7c7c6d09b Mon Sep 17 00:00:00 2001 From: iamroseyoung <16571795+iamroseyoung@users.noreply.github.com> Date: Wed, 2 Sep 2026 11:12:54 +0900 Subject: [PATCH 2/3] Update contribution-start.md --- contribution-start.md | 52 +++++++++---------------------------------- 1 file changed, 11 insertions(+), 41 deletions(-) diff --git a/contribution-start.md b/contribution-start.md index e3fe96c..55de7a0 100644 --- a/contribution-start.md +++ b/contribution-start.md @@ -1,7 +1,8 @@ ### 전자정부 표준프레임워크 GitHub Contribution 시작 가이드 -Git을 처음 사용해도 괜찮아요. -이번 목표는 Git 명령어를 모두 외우는 것이 아닙니다. 직접 문서를 수정하고 **표준프레임워크에 Pull Request(PR)를 보내는 것**이 목표입니다. +Git을 처음 사용해도 괜찮아요.
+이번 목표는 Git 명령어를 모두 외우는 것이 아닙니다.
+직접 문서를 수정하고 **표준프레임워크에 Pull Request(PR)를 보내는 것**이 목표입니다. ## 전체 흐름 @@ -20,21 +21,21 @@ Git을 처음 사용해도 괜찮아요. 11. Pull Request 보내기 → 표준프레임워크 원본 Repository --- - -# 기본 개념 - ### GitHub이란? +GitHub은 여러 사람이 소스코드와 문서를 함께 관리하고 협업하는 공간입니다.
+이번에는 표준프레임워크 문서를 수정하고, 그 결과를 GitHub를 통해 기여해 봅니다. -GitHub은 여러 사람이 소스코드와 문서를 함께 관리하고 협업하는 공간입니다. +--- -이번에는 표준프레임워크 문서를 수정하고, 그 결과를 GitHub를 통해 기여해 봅니다. +### 작업은 +개발가이드를 https://www.egovframe.go.kr/wiki/doku.php?id=egovframework:%EA%B3%B5%ED%86%B5%EC%BB%B4%ED%8F%AC%EB%84%8C%ED%8A%B8%EA%B0%80%EC%9D%B4%EB%93%9C
+github repository - https://github.com/eGovFramework/egovframe-docs 에 markdown 변환 / 보완 / 현행화 작업하는 것 --- ## 1. GitHub 계정 만들기 먼저 GitHub에서 계정을 만들고 로그인합니다. - 가입이 끝나면 나만의 GitHub 주소가 생깁니다. ```text @@ -120,7 +121,7 @@ Fork한 Repository에서 주소를 복사한 후 터미널에서 실행합니다 git clone https://github.com/내아이디/egovframe-docs.git ``` -폴더로 이동합니다. +폴더로 이동. ```bash cd egovframe-docs @@ -161,13 +162,11 @@ https://www.egovframe.go.kr/wiki/doku.php?id=egovframework:공통컴포넌트가 ``` AI가 추천한 대상 중 하나를 골라 작업을 시작합니다. - 처음이라면 너무 큰 작업보다는 **작은 문서 하나를 제대로 완성하는 것**을 추천합니다. --- ## 7. 문서 수정하기 - 바로 "수정해줘"라고 하기보다는 먼저 무엇을 수정할지 확인해 보는 것이 좋습니다. 먼저 AI에게 다음 내용을 확인합니다. @@ -264,36 +263,7 @@ eGovFramework/egovframe-docs 어떤 내용을 수정했는지 간단하게 작성하고 Pull Request를 생성합니다. -그리고 끝! 🎉 - ---- - -# 전체 흐름 다시 보기 - -```text -GitHub 계정 만들기 - ↓ -VS Code + Git + Codex 준비 - ↓ -Git 사용자 정보 설정 - ↓ -Repository Fork - ↓ -내 PC로 Clone - ↓ -AI로 Contribution 대상 찾기 - ↓ -문서 수정 - ↓ -변경사항 확인 - ↓ -git add - ↓ -git commit - ↓ -git push - ↓ -Pull Request +그리고 끝! ↓ 🎉 첫 번째 Contribution 완료! ``` From fd0e1c3dc26ba33a3c0596998e1c3e19d3451d74 Mon Sep 17 00:00:00 2001 From: iamroseyoung Date: Sun, 13 Sep 2026 06:28:03 +0900 Subject: [PATCH 3/3] Add pre-workshop environment setup guide (3rd session) --- setup-guide.md | 245 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 setup-guide.md diff --git a/setup-guide.md b/setup-guide.md new file mode 100644 index 0000000..f3cfa0f --- /dev/null +++ b/setup-guide.md @@ -0,0 +1,245 @@ +# 🧰 Spring AI 1-Day 워크샵 (3차) · 사전 환경 확인 & 설치 가이드 + +> **대상**: 참여자 (당일 오기 전 완료) +> **원칙**: 아래 🟥 **필수 6종**은 반드시 미리 끝내오세요. 10:10 환경 세팅 시간이 최대 병목이라, 사전 완료 시 당일엔 스모크 테스트(테스트 1개 실행)만 하면 됩니다. +> **무설치 강조**: 이번 3차는 **Groq 클라우드**로 실습하므로 Docker/Ollama는 **필수 아님**. 오후 RAG(14:20)를 *로컬로 직접* 돌려보고 싶은 분만 🟨 선택 항목을 설치하세요. + +--- + +## 0. 필수 / 선택 한눈에 + +```mermaid +flowchart TB + START["사전 준비"] --> M["🟥 전원 필수"] + M --> M1["① JDK 17+"] + M --> M2["② Maven 3.8.4+ (IDE 내장 가능)"] + M --> M3["③ IDE + 표준FW Extension"] + M --> M4["④ Git + GitHub 계정"] + M --> M5["⑤ Groq API Key (발급)"] + M --> M6["⑥ lab-spring-ai import"] + + START --> O["🟨 선택 · 14:20 RAG 로컬 실행 시만"] + O --> O1["⑦ Docker Desktop"] + O --> O2["⑧ Ollama 0.17.1+"] + O -. "안 깔면" .-> D["강사 라이브 데모로 대체 (문제없음)"] + + START --> R["🟩 권장"] + R --> R1["⑨ AI 코딩 에이전트 (컨트리뷰션용)"] +``` + +--- + +## 1. ⚡ 빠른 자가진단 (먼저 이것부터 실행) + +터미널에 아래를 붙여넣어 한 번에 현재 상태를 확인하세요. + +**macOS / Linux** (터미널) +```bash +echo "== JDK ==" ; java -version +echo "== Maven ==" ; mvn -version +echo "== Git ==" ; git --version +echo "== Docker(선택) ==" ; docker --version +echo "== Ollama(선택) ==" ; ollama --version +``` + +**Windows** (PowerShell) +```powershell +"== JDK =="; java -version +"== Maven =="; mvn -version +"== Git =="; git --version +"== Docker(선택) =="; docker --version +"== Ollama(선택) =="; ollama --version +``` + +> `command not found` / `찾을 수 없습니다` 가 나오면 해당 항목을 아래에서 설치하세요. +> 버전이 기준보다 낮으면(예: JDK 11, Ollama 0.16.0) **업그레이드**가 필요합니다. + +--- + +## 🟥 필수 항목 + +### ① JDK 17 이상 + +**확인** +```bash +java -version +``` +기대 출력 예시 → `openjdk version "17.0.x"` (또는 그 이상). `1.8`, `11` 이면 업그레이드. + +**설치** — Temurin(Adoptium) 권장 + +| OS | 명령 / 방법 | +|----|-------------| +| macOS (Homebrew) | `brew install --cask temurin@17` | +| macOS (수동) | https://adoptium.net → **Temurin 17 (LTS)** 다운로드 | +| Windows (winget) | `winget install EclipseAdoptium.Temurin.17.JDK` | +| Windows (수동) | https://adoptium.net → `.msi` 설치 (설치 중 **Set JAVA_HOME** 옵션 체크) | + +설치 후 새 터미널에서 `java -version` 재확인. (안 잡히면 `JAVA_HOME` 환경변수 설정 필요) + +--- + +### ② Maven 3.8.4 이상 + +> **IDE(IntelliJ/STS) 내장 Maven을 쓰면 별도 설치 생략 가능.** CLI로 빌드하려면 설치하세요. + +**확인** +```bash +mvn -version +``` +기대 출력 → `Apache Maven 3.8.4` 이상 + `Java version: 17`. + +**설치** + +| OS | 명령 / 방법 | +|----|-------------| +| macOS (Homebrew) | `brew install maven` | +| Windows (winget) | `winget install Apache.Maven` | +| 수동 (공통) | https://maven.apache.org/download → 압축 해제 후 `bin`을 PATH에 추가 | + +--- + +### ③ IDE + 표준프레임워크 Extension + +아래 중 **하나** 설치. (익숙한 것이 있으면 그대로) + +| IDE | 설치 | +|-----|------| +| **IntelliJ IDEA** (Community 무료) | macOS: `brew install --cask intellij-idea-ce` · Windows: `winget install JetBrains.IntelliJIDEA.Community` · 수동: https://www.jetbrains.com/idea/download | +| **Eclipse (STS)** | https://spring.io/tools (Spring Tool Suite) | +| **VS Code + 표준FW Extension** | macOS: `brew install --cask visual-studio-code` · Windows: `winget install Microsoft.VisualStudioCode` · 이후 확장 검색창에서 **eGovFrame Initializr** 설치 | + +--- + +### ④ Git + GitHub 계정 (컨트리뷰션 15:00용) + +**확인** +```bash +git --version +``` + +**설치** + +| OS | 명령 / 방법 | +|----|-------------| +| macOS | `brew install git` (또는 `xcode-select --install`) | +| Windows | `winget install Git.Git` · 수동: https://git-scm.com/download/win | + +**GitHub 계정**: https://github.com 가입 → 로그인 상태 준비 (Fork·PR 실습에 필요). + +--- + +### ⑤ Groq API Key 발급 *(설치 아님 · 무료 · Docker/Ollama 불필요)* + +1. https://console.groq.com 접속 → 회원가입(이메일) +2. 좌측 **[API Keys]** → **[Create API Key]** +3. 생성된 `gsk_...` 키를 복사해 안전하게 보관 (⑥에서 사용) + +> ⚠️ 실습 중 **HTTP 429 rate_limit_exceeded** 가 떠도 **키는 정상**입니다. 무료 티어 분당 요청수 제한 때문이니, 테스트를 **하나씩 개별 실행**하세요. + +--- + +### ⑥ lab-spring-ai 프로젝트 import & 키 반영 + +1. 배포받은 **`lab-spring-ai`** 프로젝트를 IDE에서 **Maven 프로젝트로 import** +2. 최초 import 시 **의존성 다운로드** 완료까지 대기 (인터넷 필요) +3. `src/main/resources/application.yml` 열어 아래를 발급 키로 교체 + ```yaml + spring: + ai: + openai: + api-key: your_api_key # ← ⑤에서 발급한 gsk_... 로 교체 + base-url: https://api.groq.com/openai + chat: + options: + model: llama-3.1-8b-instant # Step1~4 + # model: llama-3.3-70b-versatile # Step5(Tool Calling) 때 이 줄로 교체 + ``` +4. **스모크 테스트**: `Step1ChatModelTest` 의 테스트 **1개만** 실행 → 응답이 오면 준비 완료. + +> ⚠️ **Step 5(Tool Calling)** 는 모델을 `llama-3.3-70b-versatile` 로 바꿔야 안정적으로 동작합니다 (8b는 Tool 호출 불안정). + +--- + +## 🟨 선택 항목 — 오후 RAG(14:20)를 *로컬로 직접* 돌릴 분만 + +> RAG 세션은 **강사 라이브 데모가 기본**입니다. 아래를 안 깔아도 참관·학습에 지장 없습니다. 직접 실행에 도전하려는 분만 설치하세요. + +### ⑦ Docker Desktop (Redis Stack 7.4.0-v3 구동용) + +**확인** +```bash +docker --version +docker compose version +docker run --rm hello-world # 데몬 정상 동작 확인 +``` + +**설치** + +| OS | 명령 / 방법 | +|----|-------------| +| macOS | 수동(권장): https://www.docker.com/products/docker-desktop → **Apple Silicon/Intel** 맞게 다운로드 · Homebrew: `brew install --cask docker-desktop` | +| Windows | `winget install Docker.DockerDesktop` · 수동: 위 공식 페이지 → **WSL2 백엔드** 필요(설치 중 안내에 따라 활성화) | + +**설치 후**: Docker Desktop **앱을 실행**해 데몬(고래 아이콘)이 떠 있어야 CLI가 동작합니다. + +--- + +### ⑧ Ollama 0.17.1 이상 ⚠️ + +> **2차 참여자 주의**: 2차에서 쓴 **0.16.0**은 보안 이슈(CVE-2026-7482, 메모리 내 정보 노출)로 **비권장**. 반드시 **0.17.1+ 로 업그레이드/재설치**하세요. + +**확인** +```bash +ollama --version # 0.17.1 이상인지 확인 +``` + +**설치 / 업그레이드** + +| OS | 명령 / 방법 | +|----|-------------| +| macOS | 수동(권장): https://ollama.com/download → 최신본 설치(기존 버전 덮어씀) · Homebrew: `brew install ollama` | +| Windows | `winget install Ollama.Ollama` · 수동: https://ollama.com/download | + +**점심시간 팁**: 오후 RAG를 로컬로 돌릴 분은 12:00 점심 때 필요한 모델을 미리 `pull` 걸어두면 오후에 바로 시작할 수 있습니다. (모델명은 프로젝트 `application.yml` 기준 — 강사 안내) + +> ONNX 임베딩 모델(`model.onnx`, `tokenizer.json`)은 **egovframe-ai-rag 프로젝트 리소스에 포함**되어 있어 별도 설치가 필요 없습니다. + +--- + +## 🟩 권장 항목 + +### ⑨ AI 코딩 에이전트 (15:00 컨트리뷰션 세션용) + +저장소 탐색·수정 초안 작성에 사용합니다. 아래 중 **하나** 준비하면 실습 몰입도가 올라갑니다. (없어도 참여 가능) + +- **Claude Code** — https://claude.com/claude-code (설치 후 로그인) +- **Cursor** — https://cursor.com +- **Warp** — https://www.warp.dev + +--- + +## ✅ 최종 사전 체크리스트 + +**🟥 필수 (전원)** +- [ ] `java -version` → **17 이상** +- [ ] `mvn -version` → **3.8.4+** *(또는 IDE 내장 Maven 사용)* +- [ ] IDE 설치 (+ VS Code면 표준FW Extension) +- [ ] `git --version` OK + **GitHub 계정** 로그인 +- [ ] **Groq API Key**(`gsk_...`) 발급 완료 +- [ ] **lab-spring-ai** import + 의존성 다운로드 + `application.yml`에 키 반영 +- [ ] `Step1ChatModelTest` 1개 실행 → 응답 확인 (스모크 테스트) +- [ ] 📱 스마트폰 준비 (사전/사후 QR **동일 기기**) + +**🟨 선택 (RAG 로컬 실행 희망자만)** +- [ ] Docker Desktop 설치 + `docker run hello-world` 성공 +- [ ] Ollama **0.17.1+** 설치/업그레이드 (`ollama --version`) + +**🟩 권장** +- [ ] AI 코딩 에이전트(Claude Code/Cursor/Warp 중 1) 설치·로그인 + +--- + +### 도움이 필요하면 +- 당일 10:10 환경 세팅 시간에 조교가 개별 지원합니다. 다만 **필수 6종은 미리 완료**해오는 것을 강력히 권장합니다 (환경 이슈가 이 구간에 가장 몰립니다). +- 사내 프록시/방화벽 때문에 의존성 다운로드가 막히면, 프록시 설정 후 재시도하거나 당일 조교에게 문의하세요.