LMCache 기여 가이드 — 규칙 & 우리 팀 방식
[!tldr] 업무 관점 takeaway LMCache upstream에 기여하려면 세 가지를 알아야 한다: (1)
pre-commit으로 코드 품질 맞추기, (2) PR 제목·설명 형식, (3) 이슈 먼저 vs PR 먼저 판단. 우리 팀 유일한 Committer @DongDongJu가 raw_block/rust/ CODEOWNER이므로 해당 영역 PR은 그를 통해 빠르게 리뷰된다.
Claude Code Skills (자동화 도구)
LMCache repo에는 PR 워크플로우를 자동화하는 3개의 slash command가 있다. 상세 내용: [[LMCache-Claude-Skills]]
| 커맨드 | 시점 | 역할 |
|---|---|---|
/pre-pr-check | PR 전 | 코딩 표준 검사 + 자동 수정 |
/create-pr | PR 생성 | fork→upstream PR 자동 작성 |
/pr-review <번호> | 리뷰 | PR 상세 코드 리뷰 |
권장 순서: /pre-pr-check → pre-commit run --all-files → /create-pr
기본 환경 & 테스트
# 기본 브랜치: dev (항상 dev 기준으로 브랜치)
git checkout dev && git pull
git checkout -b my-feature-branch
# 설치
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e . --no-build-isolation
uv pip install -r requirements/test.txt
# 테스트 (CI와 동일)
pytest -xvs --ignore=tests/disagg \
--ignore=tests/v1/multiprocess/ \
--ignore=tests/v1/distributed/ \
--ignore=tests/skipped \
--ignore=tests/v1/storage_backend/test_eic.py
# lint (PR 전 반드시)
pre-commit run --all-files
코드 규칙
필수 사항
| 규칙 | 내용 |
|---|---|
| DCO sign-off | 모든 커밋에 Signed-off-by: 라인 필수 (git commit -s). 없으면 머지 불가 (DCO v1.1) |
| SPDX 헤더 | 모든 .py 파일 첫 줄: # SPDX-License-Identifier: Apache-2.0 |
| Import 순서 | # Standard → # Third Party → # First Party → # Local 섹션 주석 포함 |
| 타입 힌트 | 모든 함수·메서드 인자·반환값에 필수. Any 금지(애매하면 인터페이스 재설계), Optional 회피(빈 값 초기화 우선, 정말 필요하면 `X |
| Docstring | 모든 public 함수·메서드에 what/args/returns/raises 필수 |
| SLF 규칙 | 다른 클래스의 _ prefix 멤버 절대 접근 금지. CI에서 v1/multiprocess/, v1/distributed/ 강제 적용; 그 외 영역도 새 코드에서는 동일하게 적용 |
| assert 금지 | runtime validation에 assert 사용 금지 → if/raise ValueError (assert는 programmer-error invariant 체크 한정) |
| PR scope (§1.1) | PR은 작고 한 가지 목적. omnibus PR 금지 → 모듈 경계/단계(interface→구현→테스트)로 분할 |
| 테스트 | 새 기능·버그픽스에 테스트 필수. public interface 대상으로 작성 (내부 구현 직접 테스트 지양) |
canonical reference =
docs/coding_standards.md(§1~§10). 규칙 충돌 시 이 문서가 source of truth. 한국어 요약:raw/work/contribution_rules_KR.md.
언어별 lint 도구
| 대상 | 도구 |
|---|---|
| Python | ruff check/format (line-length 88) + isort + mypy + codespell |
| C++/CUDA | clang-format (Google style, 80-col) |
| Rust | cargo fmt + cargo clippy |
→ pre-commit run --all-files 한 번으로 전부 실행.
PR 제출 방식
제목 형식
[Category] prefix를 붙인다. 우리 팀 실제 사례:
| Prefix | 예시 |
|---|---|
[Feat] | [Feat] Support 3FS storage backend (#3120) |
[MP][Feat] | [MP] Add raw_block MP L2 adapter support (#3119) |
[BugFix] | [Bugfix] Fix S3 L2 adapter listener race (#3188) |
[Refactor] | [Refactor] adds unified on_complete_callback abstraction (#2393) |
[CI/CD] | [CI/CD] Add CI-safe raw-block temp-file tests (#3203) |
[Misc] | [Misc] Add .gitignore to rust/raw_block (#3129) |
[N/N][Feat] | [6/N][Feat] io_uring support to Rust raw block backend (#2635) |
PR 본문 템플릿
**What this PR does / why we need it**:
(변경 내용 + 왜 필요한지)
**Special notes for your reviewers**:
(리뷰어가 집중해야 할 부분, 알아야 할 컨텍스트)
- [ ] user facing changes → docs added
- [ ] unit tests included
이슈가 있으면:
- 닫는 경우:
Fixes #3392 - 참조만:
Refs #3392
Draft PR
코드는 있지만 리뷰 준비가 안 된 경우 Draft로 올린다. (예: daegyu94의 #3305 체크섬 검증 — 구현은 됐지만 설계 논의 중)
이슈 등록 기준
언제 이슈를 먼저 등록하는가
→ 설계 토론이 필요한 경우. 구현이 자명하면 PR 직접 올려도 무방.
| 상황 | 방식 |
|---|---|
| 기능이 크고 설계 선택지가 여러 개 | 이슈 먼저 → 토론 후 PR |
| 단순 버그픽스, 소형 개선 | PR 직접 |
| 우리처럼 external contributor | 이슈로 방향 확인 후 착수 권장 |
사례: daegyu94의 #3392 (dynamic slot allocation) — 설계 선택지(size class 수, fallback 방향, eviction 연동)가 많아서 이슈 먼저 열고 @DongDongJu에게 의견 요청 → 댓글 토론으로 방향 수렴 중.
Feature Request 형식
**Label:** new feature
**Is your feature request related to a problem?**
(문제 설명)
**Describe the solution you'd like**
(원하는 해결 방법)
**Expected Benefits**
(기대 효과)
- label
new feature필수 - 관련 Committer 태그:
@DongDongJu(raw_block 영역)
Bug Report 형식
**Label:** bug
**Describe the bug** / **To Reproduce** / **Expected behavior**
- 재현 확인 후 등록. 재현 스크립트 첨부 권장 (예: S2 버그의
repro_s2_checkpoint_overflow.py)
Committer & CODEOWNERS
Committer 조건
- 중요 feature 5개 이상 머지
- 기여 기간 3개월 이상
- 기존 Committer의 추천
현재 Samsung Committer: @DongDongJu (서동주) — 유일.
raw_block 관련 CODEOWNERS
raw_block/rust 영역 PR은 아래가 자동 리뷰어 배정:
| 파일/폴더 | 자동 배정 리뷰어 |
|---|---|
/rust/ | @DongDongJu |
/lmcache/v1/storage_backend/ | @maobaolong, @sammshen, @chunxiaozheng, @DongDongJu |
/lmcache/v1/mp_observability/ | @yoo-kumaneko, @royyhuang, @ApostaC, @OasisGit, @sammshen |
/lmcache/v1/distributed/ | @ApostaC, @maobaolong, @chunxiaozheng |
→ raw_block PR은 Samsung Committer가 리뷰어에 포함 → 우리 PR이 맥락 설명 없이도 통할 가능성 높음.
우리 팀 패치 패턴
관찰된 방식
1. 시리즈 PR (대형 기능)
DongDongJu의 Rust raw block: [1/N][Feat] → [2/N][Feat] → ... [6/N][Feat] 순차 병합.
리뷰 부담 분산 + 각 PR이 독립적으로 리뷰 가능.
2. 독립 소형 PR (개선 아이템) H1/H2/M1/M2/S1/S2 각각 = 1 PR. 서로 의존 없이 독립 착수 가능.
3. 이슈 먼저 (설계 불확실 시) #3392처럼 설계 선택지가 많으면 이슈로 @DongDongJu 의견 먼저 수렴.
4. Draft PR (작업 공개 but 미완성) daegyu94 #3305: Draft로 올려 "이 방향으로 가고 있다"는 신호 + 피드백 수집.
착수 전 체크리스트
- 같은 항목 다루는 오픈 PR 확인 (중복 방지)
- CODEOWNERS 확인 → 리뷰어 예상
- 설계 토론 필요? → 이슈 먼저 / 바로 구현 가능? → PR 직접
-
pre-commit run --all-files통과 - 테스트 추가 (기존 테스트 모두 통과)
Committer 되는 조건
LMCache Committer(MAINTAINERS.md 등재)가 되려면:
- 중요 feature 5개 이상 머지
- 3개월 이상 기여 지속
- 기존 Committer의 추천 (현재 삼성 Committer: @DongDongJu 1명)
현재 우리 팀은 external contributor 포지션. @DongDongJu가 CODEOWNER(rust/, storage_backend/)이므로 raw_block 관련 PR은 그를 통해 리뷰/머지된다.
관련 페이지
- [[Samsung-LMCache-팀]] — 팀원별 담당 영역, 오픈 PR
- [[단기-Task-목록]] — 우리가 올릴 PR 후보
- [[raw_block-개선-Task]] — H1/H2/M1/M2/S1/S2 PR 계획
- [[Issue-3392-Dynamic-Slot-Allocation]] — 이슈 먼저 올린 사례