최현수

PostgreSQL Contributor 가이드

PostgreSQL은 세계에서 가장 발전된 오픈소스 관계형 데이터베이스입니다. 이 가이드는 PostgreSQL 프로젝트에 기여하기 위한 상세한 절차를 제공합니다.

1. 사전 준비

1.1 PostgreSQL 이해하기

• PostgreSQL 문서 읽기: https://www.postgresql.org/docs/
• 아키텍처 이해: 프로세스 모델, 메모리 구조, 저장소 엔진
• SQL 표준 및 PostgreSQL 확장 기능 학습

2. 커뮤니티 참여

2.1 메일링 리스트 가입

PostgreSQL 커뮤니티는 주로 메일링 리스트를 통해 소통합니다. 가입 방법: https://www.postgresql.org/list/

2.1.1 필수 메일링 리스트

• pgsql-hackers@postgresql.org:
  • 핵심 개발 논의 (가장 중요)
  • 새로운 기능 제안 및 설계 논의
  • 패치 제출 및 리뷰
  • 기술적 이슈 토론
  • 월 300-500개 메시지

2.1.2 주요 메일링 리스트

• pgsql-bugs@postgresql.org:
  • 버그 리포트 및 수정
  • 회귀 테스트 실패 보고
  • 월 50-100개 메시지
• pgsql-docs@postgresql.org:
  • 문서 개선 제안
  • 번역 관련 논의
  • 문서 오류 수정
  • 월 20-50개 메시지
• pgsql-general@postgresql.org:
  • 일반 사용자 질문
  • 사용법 문의
  • 성능 튜닝 조언
  • 월 1000+ 메시지 (높은 트래픽)

2.1.3 전문 분야별 메일링 리스트

• pgsql-performance@postgresql.org: 성능 최적화 논의
• pgsql-admin@postgresql.org: 관리자 관련 주제
• pgsql-sql@postgresql.org: SQL 관련 질문
• pgsql-novice@postgresql.org: 초보자를 위한 리스트
• pgsql-advocacy@postgresql.org: 마케팅 및 홍보

2.1.4 메일링 리스트 활용 팁

• 구독 전 아카이브 검색: https://www.postgresql.org/search/
• 다이제스트 모드: 트래픽이 많은 리스트는 일일 요약으로 수신
• 필터링 설정: 관심 있는 키워드로 메일 필터 설정
• lurking 기간: 처음 2-4주는 관찰만 하며 분위기 파악

2.2 커뮤니티 규칙 이해

2.2.1 메일링 리스트 에티켓

• Plain Text 사용: HTML 메일 금지, 일반 텍스트만 사용
• 적절한 제목: 명확하고 구체적인 제목 작성
  • 좋은 예: [PATCH] Add support for MERGE statement
  • 나쁜 예: Question about PostgreSQL
• 인라인 답변: Top-posting 금지, 관련 부분에 직접 답변
• 과도한 인용 금지: 필요한 부분만 인용하고 답변
• 개인 공격 금지: 기술적 논의에 집중, 개인적 비판 지양
• 검색 먼저: 아카이브에서 유사한 질문이 있었는지 확인 후 질문

2.2.2 패치 제출 형식 규칙

• 패치 포맷: git format-patch 또는 unified diff 형식 사용
• 커밋 메시지 규칙:

  Brief summary (50 characters or less)
    
  More detailed explanatory text, if necessary. Wrap lines at about 72
  characters. The blank line separating the summary from the body is
  critical (unless you omit the body entirely).
    
  - Use bullet points if needed
  - Multiple paragraphs are okay
  

• 한 번에 하나의 기능: 관련 없는 변경사항을 함께 제출하지 않기
• 테스트 포함: 새 기능이나 버그 수정에는 반드시 테스트 추가
• 문서 업데이트: 사용자에게 영향을 주는 변경사항은 문서도 함께 수정

2.2.3 코드 리뷰 프로세스 이해

• 리뷰어 역할:
  • 코드 품질 검토
  • 성능 영향 평가
  • 호환성 확인
  • 테스트 커버리지 검증
• 리뷰 단계:
  1. 초기 검토: 기본적인 코드 스타일 및 컴파일 확인
  2. 기능 검토: 의도한 기능이 올바르게 구현되었는지 확인
  3. 성능 테스트: 성능 저하가 없는지 벤치마크 실행
  4. 문서 검토: 사용자 문서 및 코드 주석 확인
  5. 최종 승인: 커미터의 최종 검토 및 적용
• 피드백 처리 방법:
  • 신속한 응답: 리뷰 후 1-2주 내 응답 권장
  • 정중한 대화: 건설적인 토론으로 더 나은 해결책 모색
  • 변경사항 반영: 요청된 수정사항을 새 패치 버전으로 제출
  • 진행 상황 공유: 큰 변경사항이 필요한 경우 중간 진행 상황 공유

2.2.4 CommitFest 참여 규칙

• 패치 등록: https://commitfest.postgresql.org/에 패치 등록 필수
• 상태 관리:
  • Needs Review: 리뷰 대기 중
  • Waiting on Author: 작성자의 수정 필요
  • Ready for Committer: 커미터 검토 준비 완료
  • Committed: 메인 브랜치에 적용됨
  • Rejected: 거부됨
  • Moved to next CF: 다음 CommitFest로 이동

2.2.5 커뮤니티 문화 이해

• 기술적 우수성 추구: 완벽한 코드보다는 점진적 개선 선호
• 합의 기반 의사결정: 주요 변경사항은 충분한 논의 후 결정
• 멘토링 문화: 경험 많은 개발자들이 신규 기여자 도움
• 다양성 존중: 전 세계 다양한 배경의 개발자들과 협업
• 장기적 관점: 단기 이익보다 장기적 안정성과 호환성 중시

2.2.6 분쟁 해결 과정

• 기술적 이견:
  1. 메일링 리스트에서 공개 토론
  2. 프로토타입 구현으로 실증
  3. 성능 테스트로 객관적 비교
  4. 커미터들의 최종 판단
• 행동 강령 위반:
  1. 개인적 경고
  2. 메일링 리스트 중재
  3. 임시 활동 정지
  4. 영구 제재 (극한 상황)

3. 기여 방법 찾기

3.1 초보자를 위한 작업

3.1.1 문서 개선

• 오타 및 문법 수정:
  • doc/src/sgml/ 디렉토리의 SGML 파일들 검토
  • 영어 문법, 철자법 오류 찾기
  • 한국어 번역 기여 (PostgreSQL Korea 커뮤니티)
• 예제 추가 및 개선:
  • SQL 예제의 명확성 개선
  • 실제 사용 사례 기반 예제 추가
  • 코드 예제의 출력 결과 검증
• 설명 보완:
  • 복잡한 개념의 쉬운 설명 추가
  • 단계별 가이드 작성
  • FAQ 섹션 보강

3.1.2 테스트 케이스 추가

• 회귀 테스트 강화:
  • src/test/regress/ 디렉토리에 테스트 추가
  • 기존 기능의 엣지 케이스 테스트
  • 플랫폼별 호환성 테스트
• 성능 테스트:
  • src/test/performance/ 관련 벤치마크
  • 메모리 사용량 테스트
  • 동시 접속 테스트
• 단위 테스트:
  • C 함수별 단위 테스트
  • 경계값 테스트
  • 에러 조건 테스트

3.1.3 경고 메시지 및 에러 처리 개선

• 경고 메시지 명확화:
  • 사용자 친화적인 에러 메시지 작성
  • 해결 방법 제시 포함
  • 다국어 지원 개선
• 에러 코드 정리:
  • SQLSTATE 코드 표준화
  • 일관된 에러 리포팅
  • 로그 메시지 개선

3.1.4 코드 품질 개선

• 주석 추가:
  • 복잡한 알고리즘 설명
  • 함수 매개변수 설명
  • TODO 주석 해결
• 코드 정리:
  • 불필요한 코드 제거
  • 변수명 개선
  • 함수 분할 및 리팩토링

3.2 이슈 찾기

3.2.1 PostgreSQL Wiki TODO 활용

• Wiki TODO 리스트: https://wiki.postgresql.org/wiki/Todo
  • Easy Hacks: 초보자 친화적 작업들
  • Janitorial Projects: 코드 정리 작업
  • Features: 새로운 기능 구현
  • Performance: 성능 최적화 항목
• 카테고리별 작업:
  • SQL Features: SQL 표준 미지원 기능들
  • Administration: 관리 기능 개선
  • Reliability: 안정성 향상
  • Performance: 성능 개선
  • Monitoring: 모니터링 기능 강화

3.2.2 Open Items 추적

• 현재 개발 버전 이슈: https://wiki.postgresql.org/wiki/PostgreSQL_16_Open_Items
• 릴리스 준비 작업:
  • 버그 수정
  • 문서 업데이트
  • 테스트 커버리지 개선
  • 성능 회귀 해결

3.2.3 메일링 리스트 모니터링

• pgsql-hackers 주요 스레드:
  • “[PATCH]” 태그 포함 스레드: 기존 패치 리뷰 참여
  • “[RFC]” 태그 스레드: 새로운 아이디어 논의
  • “[BUG]” 태그 스레드: 버그 리포트 및 수정
• pgsql-bugs 활용:
  • 미해결 버그 리포트 검토
  • 재현 가능한 버그 찾기
  • 버그 수정 패치 작성

3.2.4 CommitFest 참여

• CommitFest 사이트: https://commitfest.postgresql.org/
• 참여 방법:
  • 리뷰어로 참여: 다른 사람의 패치 검토
  • 테스터로 참여: 패치 테스트 및 피드백
  • 패치 작성자: 직접 패치 제출
• CommitFest 주기:
  • 연 4회 개최 (3월, 7월, 9월, 11월)
  • 각 CommitFest는 약 1개월간 진행
  • 마감일 전까지 패치 등록 가능

3.3 고급 기여 영역

3.3.1 확장 모듈 개발

• contrib 모듈: PostgreSQL과 함께 배포되는 확장
• 개발 가능 영역:
  • 새로운 데이터 타입
  • 인덱스 접근 방법
  • 외부 데이터 래퍼 (FDW)
  • 절차 언어 확장

3.3.2 플랫폼 포팅

• 지원 플랫폼 확장:
  • 새로운 운영체제 지원
  • 아키텍처별 최적화
  • 컴파일러 호환성 개선

3.3.3 국제화 (i18n)

• 번역 작업:
  • 에러 메시지 번역
  • 문서 번역
  • 로케일 지원 개선

3.4 기여 영역별 난이도

3.4.1 입문자 (1-3개월 경험)

• 문서 오타 수정
• 간단한 테스트 케이스 추가
• 경고 메시지 개선
• 코드 주석 추가

3.4.2 초급자 (3-6개월 경험)

• 작은 버그 수정
• 기존 기능 개선
• 테스트 커버리지 확장
• 성능 벤치마크 작성

3.4.3 중급자 (6-12개월 경험)

• 새로운 SQL 기능 구현
• 확장 모듈 개발
• 복잡한 버그 해결
• 성능 최적화

3.4.4 고급자 (1년 이상 경험)

• 코어 아키텍처 변경
• 메이저 기능 개발
• 복잡한 성능 이슈 해결
• 설계 결정 참여

3.5 기여 전 체크리스트

• PostgreSQL 소스코드 빌드 성공
• 기본적인 테스트 실행 완료
• 메일링 리스트 구독 및 아카이브 검색
• 유사한 이슈가 이미 논의되었는지 확인
• 작업 범위와 예상 시간 계획 수립
• 필요한 기술 스킬 보유 확인

4. 패치 개발 과정

4.1 브랜치 생성

git checkout -b my-feature-branch

4.2 코드 수정

필요한 코드 수정

• PostgreSQL 코딩 스타일 준수
• 적절한 주석 추가
• 에러 처리 구현

4.3 테스트 작성

• 새 기능에 대한 회귀 테스트 추가
• src/test/regress/ 디렉토리에 테스트 케이스 작성

4.4 문서 업데이트

• 새 기능에 대한 문서 작성
• doc/src/sgml/ 디렉토리의 SGML 파일 수정

5. 패치 제출

5.1 패치 파일 생성

git format-patch HEAD~1  # 마지막 커밋에 대한 패치
# 또는
git diff > my-patch.patch  # 변경사항 전체 패치

5.2 패치 검증

• 코드 스타일 확인: src/tools/pgindent/ 사용
• 빌드 테스트: clean build 수행
• 테스트 실행: make check 통과 확인

5.3 메일링 리스트 제출

• 제목 형식: [PATCH] Brief description of the change
• 내용 포함사항:
  • 문제 설명
  • 해결 방법
  • 테스트 결과
  • 패치 파일 첨부

6. 리뷰 과정

6.1 피드백 대응

• 리뷰어 의견에 신속하고 정중하게 응답
• 요청된 변경사항 반영
• 업데이트된 패치 재제출

6.2 CommitFest 등록

• https://commitfest.postgresql.org/ 에서 패치 등록
• 상태 추적 및 업데이트

7. 고급 기여 활동

7.1 리뷰어 되기

• 다른 기여자의 패치 리뷰
• 코드 품질 및 성능 검토
• 테스트 및 문서 검증

7.2 장기 프로젝트 참여

• 주요 기능 개발
• 성능 최적화
• 플랫폼 포팅

8. 유용한 리소스

8.1 공식 문서

• 개발자 문서: https://www.postgresql.org/docs/devel/
• 위키: https://wiki.postgresql.org/
• 소스코드 브라우저: https://doxygen.postgresql.org/

8.2 도구

• pgindent: 코드 포맷팅
• pg_bsd_indent: 들여쓰기 도구
• Git hooks: 커밋 전 검증

8.3 커뮤니티

• IRC: #postgresql-dev (irc.libera.chat)
• Slack: PostgreSQL Slack workspace
• 회의: 온라인 개발자 미팅 참여

9. 주의사항

• 메일링 리스트를 통한 사전 논의 권장
• 대규모 변경사항은 단계별로 나누어 제출
• 백워드 호환성 유지
• 성능 영향 고려
• 충분한 테스트와 문서 제공
• 인내심 가지기: 리뷰 및 승인까지 시간이 걸릴 수 있음