디자인 문서

디자인 문서 (Design Documents)

Design 문서 인덱스와 새 문서 제안 방법을 다루는 문서예요. 디자인 문서는 Apache Pinot의 중요한 변경 뒤에 있는 동기, 기술 접근 방식, 트레이드오프를 담아요. 기여자와 운영자가 기능이 왜 그렇게 동작하는지 이해하도록 돕는 영구 기록 역할을 해요.

출처: 문서

본문

디자인 문서는 Apache Pinot의 중요한 변경 뒤에 있는 동기, 기술 접근 방식, 트레이드오프를 담아요. 기능이 왜 그렇게 동작하는지 이해할 수 있도록 기여자와 운영자에게 영구 기록을 제공해요.

목적 (Purpose)

• 정렬 (Alignment) -- 디자인 문서는 코드가 작성되기 전에 커뮤니티가 접근 방식을 검토하게 해주어 재작업을 줄여요.
• 온보딩 (Onboarding) -- 새 기여자는 디자인 문서를 읽고 주요 하위 시스템 뒤의 추론을 이해할 수 있어요.
• 감사 가능성 (Auditability) -- 디자인 문서는 아키텍처 결정의 역사적 기록을 제공해요.

디자인 문서를 언제 작성할까 (When to write a design document)

변경이 다음 중 하나를 포함한다면 디자인 문서를 작성해요:

• 새 주요 기능이나 하위 시스템 (예: 새 인덱스 타입, 새 쿼리 엔진 단계, 새 수집 경로)
• 기존 하위 시스템의 동작이나 데이터 형식을 바꾸는 중요한 변경
• 여러 Pinot 서비스(컨트롤러, 브로커, 서버, 미니언)에 영향을 주는 교차 컴포넌트 변경
• 하위 호환성에 영향을 주는 공용 API 변경

버그 수정, 작은 개선, 문서 변경은 일반적으로 디자인 문서가 필요하지 않아요.

디자인 문서 제안 방법 (How to propose a design document)

1. GitHub 이슈 열기 -- 문제와 제안된 해결책을 높은 수준에서 설명. design-doc 또는 PEP(Pinot 개선 제안)로 레이블 지정.
2. 디자인 문서 작성 -- Google Doc(또는 동등한 것)에 작성해 Pinot dev 메일링 리스트([email protected])에 공유. 포함 내용:
   • 문제 설명과 동기
   • 도움이 되면 다이어그램을 붙인 제안 디자인
   • API 또는 구성 변경
   • 고려한 대안
   • 롤아웃·하위 호환성 계획
3. 피드백 수집 -- 문서와 GitHub 이슈에서 리뷰어의 피드백을 수집.
4. 이 페이지 업데이트 -- 디자인이 수용되면 아래 인덱스 테이블에 행을 추가.
5. 구현 -- 기여 지침에 따라 기능 구현.

디자인 문서 인덱스 (Design document index)

저장소 내 디자인 문서 (In-repo design docs)

2025

2024

2022

2021

2020

2019 및 이전 (2019 and earlier)

더 알아보기 (Learn more)

• 세그먼트 라이터 API (Segment Writer API)
• 기여 지침 (Contribution Guidelines)