유지보수와 변경 규모(합의)
이 문서는 핵심 유지보수자와 자주 기여하는 사람을 대상으로 합니다. 기여 가이드, 커밋과 PR 규칙과 함께 읽으세요. 목표는 기여를 환영하면서도 통제하기 어렵고 되돌리기 힘든 대규모 변경을 최대한 피하고, main과 downstream fork가 안정된 형태에서 멀어지는 위험을 줄이는 것입니다.
원칙
- 작게, 리뷰 가능하게, 되돌릴 수 있게: 리뷰하기 어려운 거대한 “한 번에 전부” 변경보다 초점이 분명한 PR 여러 개가 낫습니다.
- 코드 작성 전에 의도부터 맞추기: 동작이나 데이터 계약에 영향을 주는 변경은 가능하면 Issue / Discussion에서 범위를 먼저 맞춘 뒤 PR을 엽니다.
- 핵심 경로 지키기: 데이터 계층, 라우트, 전역 설정, 빌드와 내보내기 흐름은 전체 사이트에 영향을 줍니다. PR에는 동기, 위험, 검증 방식을 명확히 적어야 합니다.
- 무관한 리팩터링 끼워 넣기 금지: 대규모 이름 변경, 저장소 전체 포맷팅, 메이저 의존성 업그레이드를 무관한 bugfix/기능과 같은 PR에 섞지 않습니다. 필요하면 분리합니다.
- 의존성과 툴체인: 프레임워크 메이저 버전, lockfile 전략 변경은 이유, 호환성을 깨는 변경, 회귀 검증(빌드, 핵심 경로 테스트 등)을 설명해야 합니다.
권장 PR 크기
| 유형 | 권장 방식 |
|---|---|
| Bug 수정 | 최소 변경 + 테스트 또는 재현 설명 |
| 작은 기능 / 단일 테마 | 가능하면 테마 디렉터리나 단일 모듈 경계 안으로 제한하고, 공유 계층을 함께 건드리지 않습니다 |
| 다중 테마 / public API | Issue에서 인터페이스와 기본값을 먼저 맞추고, 마이그레이션 경로를 문서에 적습니다 |
| 호환성을 깨는 변경 | 버전과 설정 마이그레이션을 명확히 적고, 필요하면 단계별로 나눠 리뷰하기 쉽게 만듭니다 |
영향이 큰 영역(더 자세한 설명 필요)
아래 변경은 전체 사이트나 여러 테마에 영향을 주는 경우가 많습니다. PR 설명과 검증 설명을 더 완전하게 작성해야 합니다(2인 리뷰 필수 여부는 저장소 소유자와 유지보수자가 함께 정합니다).
lib/db/(SiteDataApi, Notion 가져오기와 캐시 포함)pages/아래의 SSG/ISR, i18n, 빌드 라이프사이클 관련 로직next.config.js와 내보내기/빌드 스크립트- 전역 설정(
blog.config.js,lib/config.js및 유사 기본 동작) - 보안 관련: 인증, 비밀 키, 서드파티 콜백, CSP 등
프로젝트가 “너무 멀리 흘러가지” 않게 하기
- 소수 사이트만의 가정은 가능하면 옵션이나 설정 항목으로 만듭니다. 모두에게 영향을 주는 전역 기본값에 넣지 않습니다.
- 테마 격리: 테마 전용 로직은
themes/<name>/에 두고, 특정 테마의 UI나 라우트 가정을 공유 계층에 쓰지 않습니다. - 문서 동기화: 사용자가 볼 수 있는 동작이나 설정 항목이 바뀌면 같은 PR 또는 바로 이어지는 PR에서 문서를 갱신합니다(한국어/영어는 상황에 맞게).
GitHub 권한(저장소 소유자용)
저장소 소유자(개인 저장소 소유자 또는 조직 Owner)는 Settings → Collaborators(또는 조직의 Teams / Repository access)에서 신뢰하는 유지보수자(예: @qianzhu18)를 초대하고 신뢰 수준에 따라 Write / Maintain / Admin 역할을 부여할 수 있습니다. 브랜치 보호 변경이나 일부 저장소 설정 관리가 필요한지에 따라 Maintain 또는 Admin을 선택합니다.
브랜치 보호 또는 서드파티 검사(예: 배포 권한 필요) 때문에 병합이 자주 막힌다면, Settings → Branches에서 신뢰하는 유지보수자에게 bypass를 설정하거나, 어떤 상황에서 누가 대신 병합할지 소유자와 유지보수자가 문서로 합의합니다.
GitHub UI 문구는 제품 변화에 따라 달라질 수 있습니다. 누가 병합할 수 있는지, 언제 검사를 우회할 수 있는지 같은 거버넌스 규칙은 기본 설정에만 기대지 말고, 유지보수자 사이에 문자로 합의(Issue, Discussion 또는 이 저장소 문서의 개정 설명)를 남기는 것이 좋습니다.
관련 문서
이 문서는 프로젝트 변화에 따라 수정할 수 있습니다. 큰 수정은 Issue 또는 Discussion에 배경을 한 줄 남겨 이후 기여자가 이해하기 쉽게 하는 것을 권장합니다.