Skip to content

Latest commit

 

History

History
128 lines (97 loc) · 9.37 KB

CONTRIBUTING.md

File metadata and controls

128 lines (97 loc) · 9.37 KB

기여 및 커밋 규칙

대상 저장소: tiemo0708/Notification-Lab

코드 변경의 목적, 설계 판단, 실제 검증 결과를 추적한다. 현재 구현 범위는 README.md, 다음 작업은 PLAN.md와 docs/PROGRESS.md에서 확인한다.

커밋 메시지

Conventional Commits 1.0.0를 기반으로 한다. 타입과 영역은 영문 소문자, 제목과 본문은 한글로 작성한다. 아래 예시는 형식을 설명하기 위한 것이며, 해당 기능의 구현 완료를 뜻하지 않는다.

타입(영역): 변경 내용

변경 이유와 주요 설계 판단
검증 방법과 실제 결과 또는 실행하지 못한 이유

Refs: #이슈번호
  • 영역, 본문, 이슈 참조는 필요한 경우에 작성한다. 이슈가 없으면 번호를 만들지 않는다.
  • 트랜잭션, 전달 보장, 동시성, 성능 관련 변경은 이유와 검증 결과를 본문에 남긴다.
  • 제목은 한 줄로 간결하게 쓴다. 수정, 작업 중, 최종 같은 모호한 표현은 피한다.
  • 권장 영역: api, notification, provider, outbox, kafka, worker, batch, load-test.
  • 프로젝트 전체에 적용되는 변경은 영역을 생략할 수 있다.
타입 사용 목적 예시
feat 기능 추가 feat(outbox): 알림과 발행 이벤트의 원자적 저장 구현
fix 버그 수정 fix(worker): 처리 완료 전 오프셋 커밋 방지
refactor 외부 동작을 유지하는 구조 개선 refactor(provider): 푸시 발송 인터페이스 분리
perf 성능 개선 목적의 변경 perf(outbox): 미발행 이벤트 조회 인덱스 추가
test 테스트만 추가하거나 수정 test(kafka): 브로커 장애 복구 시나리오 추가
docs 문서와 실험 결과 기록 docs(load-test): 컨슈머 수에 따른 처리량 비교 기록
ci 자동 빌드와 테스트 설정 ci: PR 테스트 워크플로 추가
build 의존성과 빌드 설정 build: MySQL 드라이버와 Flyway 의존성 추가
chore 기타 관리 작업 chore: 빌드 산출물 제외 규칙 추가

여러 타입이 연관되는 변경은 주목적으로 분류한다. 예를 들어 기능 코드와 해당 기능의 테스트를 함께 추가하면 feat를 사용한다.

호환성이 깨지는 변경

타입/영역 뒤에 !를 붙이고, 본문에 영향과 전환 방법을 설명한다. BREAKING CHANGE: 꼬리말로 구체적인 변경 계약을 남기는 것을 권장한다. API 응답 코드, 응답 필드, 이벤트 스키마 변경도 검토 대상이다.

feat(api)!: 알림 생성 API를 비동기 접수 방식으로 전환

요청과 outbox 이벤트를 저장한 뒤 접수 응답을 반환한다.
클라이언트는 조회 API로 이후 처리 결과를 확인한다.

BREAKING CHANGE: POST /notifications 응답이 최종 처리 결과를 담은 201에서 접수 결과를 담은 202로 바뀐다.

커밋 단위와 검증

  1. 한 커밋은 독립적으로 설명하고 되돌릴 수 있는 논리적 변경 하나로 구성한다.
  2. 기능과 이를 검증하는 테스트는 같은 커밋에 포함할 수 있다.
  3. 관련 없는 리팩터링과 기능 추가는 분리한다. 타입을 맞추기 위해 컴파일되지 않는 단위로 쪼개지 않는다.
  4. 커밋 전에 변경 파일과 스테이징된 diff를 확인하고, 비밀정보나 무관한 파일을 포함하지 않는다.
  5. 기본 검증은 ./gradlew test이다. Windows에서는 gradlew.bat test를 사용한다.
  6. 추가 통합/부하 테스트가 필요한 변경은 해당 명령과 결과도 남긴다.
  7. 실행하지 못한 검증은 미실행 이유와 남은 위험을 기록한다. CI나 테스트 통과를 추정하지 않는다.
  8. perf라는 타입 자체가 개선의 증거는 아니다. 수치는 실제 측정한 경우에만 제시한다.

성능 실험은 데이터 수, 실행 명령, JDK/인프라, CPU/메모리, 동시성, 설정값, 반복 횟수와 변경 전후 결과를 함께 남긴다. 공급자 수락과 단말 도착, 단일 인스턴스 결과와 전체 시스템 결과를 구분한다.

브랜치와 PR

  • 혼자 개발하는 기본 흐름은 main에서 작은 논리적 단위로 직접 커밋하는 방식이다. develop은 두지 않는다.
  • 기존 실행 버전을 유지해야 하는 큰 실험에만 작업 브랜치를 만든다. 이름은 feat/outbox-persistence, fix/worker-offset처럼 작성한다.
  • PR은 선택 사항이다. 사용하면 커밋 형식의 제목과 변경 이유/범위/검증/한계를 기록하고 템플릿을 따른다.
  • PR을 사용한 변경은 관련 테스트와 diff 검토 후 Squash merge할 수 있다. 자동 병합하지 않는다.
  • 매 커밋마다 푸시할 필요는 없다. 작은 논리적 변경은 로컬 커밋으로 쌓고, 검증된 단계나 작업 세션 종료 시 사용자가 검토한 커밋들을 함께 푸시한다. 푸시 전 커밋은 해당 컴퓨터에만 있으므로 원격 백업이 아니다.
  • 작업 순서: 완료 조건 정의 -> 구현 -> 테스트 -> diff 확인 -> 결과 기록 -> 로컬 커밋 -> 사용자 검토 -> 푸시.
  • AI 도구는 푸시 전에 변경 이유, 확인할 파일, 실제 테스트 결과, 미검증 항목, 커밋을 제시하고 사용자의 푸시 승인을 기다린다.
  • 테스트 실패 또는 핵심 완료 조건 미검증 상태를 완료로 보고하거나 푸시하지 않는다.
  • 게시된 이력을 임의로 재작성하지 않는다. force push, 자동 병합, 보호 규칙 우회는 하지 않는다.
  • 원격 커밋/푸시/PR 생성과 병합은 각각 사용자 요청 범위 및 실제 권한을 확인한 뒤 진행한다.
  • 원격 상태를 확인할 수 없다면 기존 main이나 README 유무를 추정해서 덮어쓰지 않는다.

.github/pull_request_template.md를 PR 작성 체크리스트로 사용한다. 문서만으로 CI나 브랜치 보호가 자동 설정되는 것은 아니다. 미설정 기능을 설정 완료로 기록하지 않는다.

코드와 테스트

  • 빌드는 Gradle Wrapper 8.14.5와 Groovy DSL(build.gradle, settings.gradle)을 사용한다. 의존성 버전은 기존 Spring Boot BOM을 따른다.
  • Java 21, UTF-8, 공백 4칸을 사용한다. YAML은 공백 2칸이다. .editorconfig를 따른다.
  • 클래스/record/interface는 UpperCamelCase, 메서드/변수는 lowerCamelCase, 상수는 UPPER_SNAKE_CASE로 작성한다.
  • dev.jinhyeon.notificationlab 아래 api, notification, provider, config 패키지를 유지한다. 새 패키지는 실제 책임이 생길 때 추가한다.
  • 생성자 주입을 사용하고 컨트롤러는 HTTP 변환과 입력 검증, 서비스는 처리 흐름, 저장소는 데이터 접근을 담당한다.
  • 트랜잭션 경계를 코드와 문서에 명시한다. 외부 공급자 호출 중 DB 트랜잭션을 유지하지 않는다.
  • 새 import는 와일드카드를 피한다. 규칙 적용을 위해 관련 없는 기존 파일을 일괄 수정하지 않는다.
  • 테스트 클래스는 대상Test, 메서드는 검증하는 동작을 설명하는 영문 lowerCamelCase로 작성한다.
  • 기본 ./gradlew test에서 단위/HTTP/실제 MySQL 테스트를 실행한다. DB/Kafka 검증은 Testcontainers를 사용하며 Docker가 없다고 자동 스킵하지 않는다.
  • 테스트 데이터는 가상 값만 사용한다. 구현을 그대로 반복하는 테스트보다 동작, 실패, 동시성, 트랜잭션 경계를 검증한다.

DB와 API

  • 테이블/컬럼은 소문자 snake_case, 인덱스는 idx_, 유니크 제약은 uk_, 외래 키는 fk_, 체크 제약은 chk_ 접두사를 쓴다.
  • 스키마 변경은 V번호__설명.sql Flyway migration으로 관리한다. 적용된 migration은 수정하지 않고 다음 버전을 추가한다.
  • 저장 시간은 UTC, DB 시간 정밀도는 마이크로초로 통일한다. UUID는 문자열 식별자로 저장한다.
  • JSON 필드는 lowerCamelCase, 상태 값은 UPPER_SNAKE_CASE를 사용한다. 오류 응답에 payload/DB 오류 상세를 노출하지 않는다.
  • 현재 기본 실행(S3)은 요청/Outbox 커밋 후 HTTP 202를 반환한다. sync(S2), memory(S1) 비교 프로필은 동기식 HTTP 201을 유지한다.

CI

  • .github/workflows/test.yml은 push와 PR에서 Java 21로 ./gradlew --no-daemon --console=plain build를 실행한다.
  • Docker를 제공하는 GitHub hosted runner에서 실제 MySQL/Kafka 테스트와 실행 JAR 생성까지 확인한다. Gradle 의존성 캐시를 사용한다.
  • CI 결과는 원격 실행 결과를 확인한 경우에만 통과로 기록한다. 브랜치 보호 및 자동 포맷터는 현재 설정하지 않는다.

비밀정보와 산출물

.env, 비밀번호, AWS 키, FCM 서비스 계정 키, 실제 디바이스 토큰, 수신자 데이터, 로컬 인증 설정, 빌드 산출물을 커밋하지 않는다. 설정 예시는 실제 비밀값을 제거한 샘플로만 제공한다. .gitignore에 있다고 이미 추적 중인 파일의 비밀정보가 제거되는 것은 아니다.

AI 작업 도구

AGENTS.md를 함께 따른다. 별도 에이전트나 특정 AI 제품은 필수 조건이 아니다. 현재 구현과 계획, 실제 테스트와 예상 결과, 로컬 변경과 원격 반영 상태를 구분해서 보고한다.