eGovFRAME · CONTRIBUTOR FIELD GUIDE

처음 시작하는
표준프레임워크
기여

작게 관찰하고, 근거를 모으고,
끝까지 확인하는 방법

2026년 실제 PR과 리뷰에서 배운 점 · 기존 기여 안내의 후속 자료

문제
→ 근거
→ 작은 수정
→ 확인

eGovFrame Contribution Starter01 / 20

CONTENTS · 전체 목차

발표 흐름 한눈에 보기

항목을 누르면 해당 슬라이드로 이동합니다.

관점 → 실제 기여 → 리뷰 대응 → 다음 기여02 / 20

01 · 관점

“

기여는 코드 추가보다
문제 해결에서 시작한다

1사용자가 겪는 불편을 찾는다

2왜 문제인지 근거를 확인한다

3작고 분명한 수정으로 제안한다

4실제 사용 흐름까지 확인한다

예: 파일 다운로드 이름을 가이드와 맞추고, 원인과 수정 방법을 PR #1167에서 설명했습니다.

assertEquals("attachment; filename=원본파일.txt", header); · 실제 테스트에 쓰인 단위 테스트 예

좋은 PR은 문제와 해결을 함께 설명합니다03 / 20

02 · 아이디어 찾기

첫 기여 후보는
가까운 곳에 있다

01

사용 설명

깨진 링크, 빠진 단계, 따라 했을 때 막히는 안내를 찾아봅니다.
예: 문서 제목 단계를 정리한 PR #729

### 필드 관리문서 · 설치 가이드

02

작은 품질 문제

다시 만들 수 있는 버그나, 규칙이 분명한 순수 유틸리티를 살펴봅니다.
예: 파일명 규칙과 테스트를 함께 다룬 PR #1167

assertEquals(expected, actual);버그 · 작은 테스트

03

안전한 운영

실제로 쓰이는 취약 의존성, 실행 설정, 환경 안내를 확인합니다.
예: 업로드 경로와 지속 저장소를 보완한 PR #121

mountPath: /app/files보안 · 배포 · CI

문제의 크기보다 저장소와의 적합도가 먼저입니다04 / 20

03 · 수정 전 확인

코드보다 먼저
맞는 자리를 찾는다

저장소의 역할, 기본 브랜치, 이미 있는 해결책부터 확인합니다.

저장소의 기본 브랜치 · 보통 main

저장소가 맡은 역할과 README

최근 PR 회신과 중복 변경

변경이 다른 기능을 건드리는지

예: 문서 저장소에는 안내 오류, 템플릿 저장소에는 실행 설정을 제안합니다. git remote -v로 내 복사본과 원본 주소를 먼저 확인합니다.

일반 기여는 해당 저장소의 기본 브랜치에서 시작05 / 20

04 · 공개 기여 기록에서 배운 점

결과마다 다음 행동이 달랐다

219병합 완료 · 해결 방법을 다음 기여에 활용

4열린 PR · 회신과 추가 요청을 확인

262병합 없이 닫힘 · 저장소의 수용 범위를 다시 확인

2026.09.12 공개 GitHub 조회 · 건수는 경험의 배경이며, 기여의 목표가 아닙니다

is:pr org:eGovFramework author:dasomel is:open is:pr org:eGovFramework author:dasomel is:merged is:pr org:eGovFramework author:dasomel is:closed -is:merged · 열린 PR · 병합 · 병합 없이 닫힌 PR 검색 조건

배운 점: 문제를 작게 고르고, 회신을 반영하고, 실제 동작으로 확인하기06 / 20

05 · 실제 반영한 것

기여는 코드 밖까지 이어졌다

✓

보안

사용 여부를 먼저 확인하고, 취약점이 연결되는 의존성을 업데이트
예: PR #61은 CVE-2024-38999 대응

implementation 'org.webjars:webjars-locator-core:0.59'

≋

읽기 쉬운 코드

반복 getter/setter를 정리하되 방어 로직은 유지
예: PR #1031은 네 개 VO의 반복 코드를 줄였습니다

@Getter @Setter

▣

실행과 배포

실제 사용 설명과 실행 점검을 보완
예: PR #74의 9개 Deployment에 점검 설정 추가

readinessProbe:

↗

문서와 품질

작고 재현 가능한 오류를 바로잡고 확인
예: PR #729 문서 제목 · #916 전화번호 마스킹

maskPhoneNo("010-1234-5678") → "010-****-5678"

변경 종류는 달라도 기준은 하나: 실제 필요와 검증07 / 20

06 · 회신 → 수정 → 병합

회신이 해결을 더 정확하게 만들었다

#1167common-components파일 다운로드 이름

문제

파일 이름 속성 키와 내려받기 헤더가 가이드와 맞지 않았습니다.

회신

가이드 키로 통일하고, 속성값 처리와 파일명 헤더 문자열 테스트를 요청했습니다.

수정

5개 테스트 사례를 추가해 병합됐습니다. 실제 HTTP 응답 호출 자체를 시험한 것은 아닙니다.

assertEquals("attachment; filename=원본파일.txt", header); · 속성값에서 다운로드 헤더 문장을 만드는 테스트

PR #1167 원문 보기 · 2026.08.26 병합 · 실제 HTTP 응답 호출은 테스트 범위 밖

리뷰는 사람의 기대와 코드의 실제 동작을 맞추는 과정08 / 20

07 · 실행 경로로 검증하기

겉보기 설정이 아니라
사용 흐름을 따라간다

브라우저

사용자가 파일을 올린다

→

애플리케이션

읽기 전용 컨테이너의 쓰기 경로를 점검

→

지속 저장소

재기동 후에도 업로드 파일을 보존

mountPath: /app/files
claimName: egovframe-template-simple-backend-files

#121경로 설정과 PVC를 추가해 업로드 실패 가능성을 보완. 실제 클러스터 E2E 검증은 하지 않았다고 PR에 밝혔습니다.

확인한 것과 확인하지 못한 것을 함께 적기09 / 20

08 · 회신을 행동으로 바꾸기

회신은 세 곳에 올 수 있다

일반 댓글리뷰 본문코드 줄 의견

관찰

오류 안내가 사용자가 보는 응답까지 이어지는지 확인

→

수정

#28·#29 폴백을 실제 스트리밍 경로에 연결

→

확인

폴백 값이 스트리밍 응답으로 돌아오는지 점검

return Flux.just(fallbackHandler.getFallbackMessage(e)); · 공개 PR #28의 실제 코드

쉽게 읽기Flux는 데이터를 이어 보내는 응답 흐름이고, just는 안내 문장 한 개를 그 흐름에 담습니다. 오류 안내가 실제 응답으로 전달돼야 합니다.

사례: 공개 PR #28·#29 · 스트리밍 오류 폴백10 / 20

09 · 닫힌 PR에서 배우기

끝까지 밀기보다
방향을 다시 본다

수정은 저장소 목적에 맞게

common-components #1166은 유틸 테스트만 추가한 PR이었지만, 샘플 저장소의 관리 범위와 맞지 않아 닫혔습니다.

먼저 비슷한 변경이 받아들여졌는지 살펴봅니다.

닫힘에서 다음 방향 찾기

큰 변경을 계속 밀기보다, 회신을 읽고 더 작은 문제나 다른 저장소를 고를 수 있습니다.

반려 이유를 다음 PR의 사전 점검에 활용합니다.

maskPhoneNo("010-1234-5678") → "010-****-5678" · 공개된 유틸 PR #916의 작고 확인 가능한 예

반려 사례 #1166 원문 · 반영된 유틸 사례 #916

닫힘은 낭비가 아니라 다음 판단을 위한 신호11 / 20

10 · 첫 PR의 흐름

작은 한 건을
끝까지 완성한다

1 · 저장소 고르기문제와 저장소 역할을 연결합니다.
예: 제목 단계 정리는 egovframe-docs

2 · 원본 확인기본 브랜치와 최신 변경을 봅니다.
예: 열린 PR에서 중복 여부 확인

3 · 작업 공간 분리Fork와 작업 브랜치를 준비합니다.
예: fix/docs-link 브랜치

4 · 한 문제 수정관련 파일만 바꾸고 중복을 줄입니다.
예: 문서 제목 단계를 고친 #729

5 · 근거로 검증테스트·빌드·화면 흐름을 확인합니다.
예: 링크가 열리는지 직접 확인

6 · PR과 회신영향과 한계를 설명하고 후속 대응합니다.
예: #1167에 테스트 보완 회신 반영

git switch -c fix/docs-link git diff --check · 새 작업 공간 만들기와 공백 오류 확인

Fork = 내 복사본 · upstream = 원본 저장소 · branch = 작업 공간12 / 20

11 · 제안서처럼 쓰기

PR은 짧아도
근거는 분명하게

✓무엇이 불편하고 왜 고쳤는가?

✓변경은 한 가지 주제인가?

✓어떤 명령·화면·테스트로 확인했나?

✓실행 환경에서 확인하지 못한 부분은?

변경 코드 예:

String header = buildContentDispositionHeader(request);
assertEquals("attachment; filename=원본파일.txt", header);

본문 예: 문제(키 불일치) / 변경(키 통일) / 확인(문자열 테스트) / 미검증(HTTP 응답 연결)
실제 사례: common-components PR #1167

근거가 명확하면 리뷰어가 확인할 경로도 짧아집니다13 / 20

12 · AI 활용 전략

AI의 초안을
확인 가능한 변경으로 바꾼다

A · AI에게 맡길 작업 예시

찾기 → 비교 → 테스트 초안

“오류가 난 뒤 응답까지 이어지는 함수를 찾아줘.”
“수정 전후의 차이와 빠진 경우를 비교해줘.”
“정상 응답과 오류 안내를 확인할 테스트를 제안해줘.”

B · 작성자가 확인할 것

원본 코드 → 실행 → 결과

함수가 실제로 호출되는지 코드를 따라갑니다. 테스트를 직접 실행하고 예상한 응답과 비교합니다.
예: 오류 때 안내 문장이 사용자에게 전달되는지 확인하고, 못 해 본 실행 조건은 PR에 적습니다.

return Flux.just(fallbackHandler.getFallbackMessage(e)); · 공개 AI-RAG PR #28의 실제 코드

위 질문은 AI 활용 방법의 예시이며, 해당 PR의 AI 사용 이력을 뜻하지 않습니다. Flux.just는 안내 문장 한 개를 응답 흐름에 담습니다. 제품에 새 AI 기능을 넣는 큰 제안은 먼저 이슈로 논의합니다.

AI는 속도를 돕고, 결과 검증은 작성자가 맡습니다14 / 20

13 · 앞으로의 방향

다음 기여는
더 잘 고르는 일에서 시작한다

→

반복되는 불편부터 찾기: 예를 들어 문서 링크 오류나 처음 실행이 막히는 단계

저장소의 방향에 맞는지 확인: 문서는 안내, 배포 도구는 설치 설정을 고치기

큰 제안은 이슈로 먼저 묻기: 예를 들어 여러 모듈의 공통 AI 구조 변경

검증 범위를 공개하기: #121처럼 YAML은 확인했지만 실제 클러스터 실행은 못 한 경우

한 PR씩 마무리하기: #1167처럼 회신을 반영해 좁은 문제를 완료

git diff --check · 작게 고친 뒤 마지막에 변경 내역 공백 오류까지 확인

빠른 기여보다 오래 유지될 기여를 찾습니다15 / 20

14 · 커뮤니티 프로젝트 찾기

awesome-egovframe

유용한 도구를 찾아 소개하는 일도 기여입니다. 예를 들어 샘플 실행을 돕는 Launcher를 이 목록으로 알릴 수 있습니다.

PR #4AI 스타터 · 개인정보 가림, 오류와 사용량 기록 PR #5공공데이터 · API 키와 페이지 조회를 돕는 도구 PR #6관측성 · 로그와 서비스 상태를 살피는 도구 PR #9국산 암호 · SEED·LEA 설정을 돕는 도구 PR #10접속기록 · 개인정보 처리 기록을 남기는 도구 PR #11RAG 평가 · 답변 근거를 확인하는 JUnit 5 도구 PR #14egovframe-launcher · 샘플 실행 보조 도구

egovframe-launcher 대시보드 화면 — egovframe-launcher 대시보드 · 이미지를 누르면 크게 보기

- [dasomel/egovframe-launcher](https://github.com/dasomel/egovframe-launcher) - eGovFrame 샘플의 복제·빌드·실행을 돕는 데스크톱 도구. · 내 프로젝트로 작성한 등재 예시

새 항목은 공개 여부·이용 조건(라이선스)·README 안내·최근 관리 상태를 확인합니다. 저장소 · 기여 안내 · 7건 모두 병합

커뮤니티의 도구 목록 · 등재가 공식 인증이나 품질 보증을 뜻하지는 않습니다16 / 20

15 · 개발 시작을 쉽게

egovframe-launcher로
샘플 실행을 단순하게

첫 실행에서 기여 거리 찾기

등록된 샘플을 복제·빌드·실행하고 브라우저로 엽니다.
예: 안내대로 실행하다 막힌 단계와 오류 로그를 기록하면 문서 보완의 출발점이 됩니다.

프로젝트 유형별 실행

Spring Boot 실행, WAR 빌드 후 별도 Tomcat 실행처럼 준비된 경로를 제공합니다.
예: WAR 샘플은 Tomcat 경로를 지정한 뒤 배정된 포트로 실행합니다.

미리 준비할 것

기본 준비물은 Git, JDK 17(자바 개발 도구), Maven(빌드 도구)입니다. 샘플에 따라 Node.js/npm(React 준비 도구), Docker(서비스 실행 상자), Tomcat(자바 웹 앱 실행기)도 필요합니다.

기대 범위를 알기

미리 등록된 대상 프로젝트를 위한 실행 보조 도구입니다. 모든 저장소를 지원하거나 필요한 도구를 전부 설치해 주는 범용 IDE는 아닙니다.
예: 목록에 없는 앱은 수동 준비가 필요할 수 있습니다.

git --version java -version mvn -v ./egov-launcher-darwin-arm64 · macOS Apple Silicon 실행 예 · 다른 환경은 Releases에서 맞는 파일 선택

launcher 저장소 · 실행 파일 받기 · 커뮤니티 프로젝트이며 공식 제품 인증을 뜻하지 않습니다.

도구가 준비를 도와도 실행 환경 조건은 확인해야 합니다17 / 20

16 · 기여 절차 용어

PR과 변경 관리 용어

PR: 변경을 검토하고 합쳐 달라는 요청예: 파일 이름 처리 PR #1167
브랜치: 서로 다른 작업을 나누는 공간예: 문서 수정용 fix/docs-title
main: 대개 새 변경이 모이는 기본 줄기예: 저장소의 기본 브랜치
Fork: 내 계정에 만드는 작업용 복사본예: 내 계정에 docs 저장소 복제
upstream: 원래 프로젝트의 저장소예: eGovFramework 원본 주소
CI: 코드를 자동으로 빌드·검사하는 절차예: PR 때 자동 테스트 실행
CVE: 공개 보안 취약점에 붙는 식별번호예: PR #61은 CVE 번호를 제목에 표시
E2E: 사용자 요청부터 결과까지 확인하는 테스트예: 업로드 후 파일이 다시 열리는지 시험
PVC: 쿠버네티스에서 파일을 보관할 저장 공간 요청예: 앱을 다시 시작해도 업로드 파일 유지
Lombok: 반복 getter·setter 코드를 자동으로 만드는 도구예: 단순 VO의 반복 코드를 줄인 #1031

git switch -c fix/docs-link @Getter @Setter · 브랜치 만들기와 VO 반복 코드 줄이기 예

뜻과 함께 실제 기여에서 쓰인 예를 확인하세요18 / 20

17 · 실행과 데이터 용어

앱 실행과 데이터 용어

PII: 이름·전화번호처럼 사람을 알아볼 정보예: 개인정보 마스킹 유틸 PR #916
RAG: 문서를 찾아 참고한 뒤 AI가 답하는 방식예: 안내문을 찾고 그 내용으로 답하기
Docker: 프로그램과 실행 파일을 한 상자에 담는 도구예: 앱과 필요한 런타임을 이미지로 포장
Compose: 여러 프로그램 상자를 함께 시작하는 설정예: 앱과 데이터베이스를 같이 실행
Kubernetes: 여러 서버에서 프로그램 상자를 관리하는 시스템예: 앱을 띄우고 필요한 수만큼 유지
README: 저장소의 소개와 사용 방법을 적은 문서예: 설치 순서와 실행 명령 안내
VO: 이름·주소 같은 값을 담아 전달하는 자바 객체예: 반복 코드를 정리한 PR #1031
YAML: 프로그램 설정을 적는 읽기 쉬운 글 형식예: 앱을 띄울 배포 설정 파일
WAR: 자바 웹 앱을 배포할 때 묶는 파일예: Tomcat에 올려 실행
Tomcat: 자바 웹 앱을 실행해 주는 프로그램예: WAR 앱을 별도 포트로 실행

docker compose up kubectl apply -f k8s/ · 컨테이너와 배포 설정 실행 예

뜻과 함께 실제 기여에서 쓰인 예를 확인하세요19 / 20

18 · 공개 근거와 다음 한 걸음

오늘 할 일은
불편 하나를 기록하는 것

문제 · 근거 · 작은 해결 · 확인 방법
네 줄이면 첫 제안이 시작됩니다.

관찰에서 시작

문제=___ · 근거=___ 수정=___ · 확인=___

보안 PR #61CVE-2024-38999 대응 배포 PR #74서비스 점검 설정 보완 Lombok PR #1031VO 반복 코드 정리 유틸 테스트 PR #916개인정보 마스킹 함수와 테스트 문서 PR #729제목 단계 정리 회신 반영 PR #1167파일 다운로드 이름 처리 배포 PR #121업로드 경로와 파일 저장 AI 기능 PR #28스트리밍 오류 폴백 AI 기능 PR #29오류 응답 화면 연결 awesome-egovframe커뮤니티 프로젝트 목록 egovframe-launcher샘플 실행 보조 도구

공개 GitHub 근거 · 기여 현황 조회 기준 2026.09.1220 / 20

처음 시작하는표준프레임워크기여