사용자 대상 기능을 추가, 변경, 삭제하거나 Bazel에 중요한 아키텍처 변경을 적용하려면 변경사항을 제출하기 전에 반드시 디자인 문서를 작성하고 검토를 받아야 합니다.
다음은 중요한 변경사항의 몇 가지 예입니다.
- 네이티브 빌드 규칙 추가 또는 삭제
- 기본 규칙 관련 브레이킹 체인지
- 2개 이상의 규칙의 동작에 영향을 미치는 네이티브 빌드 규칙 의미 체계 변경사항
- Bazel의 규칙 정의 API 변경사항
- Bazel이 다른 시스템에 연결하는 데 사용하는 API 변경사항
- Starlark 언어, 시맨틱 또는 API 변경사항
- Bazel 성능 또는 메모리 사용량에 총체적인 영향을 미칠 수 있는 변경사항 (좋든 나쁘든)
- 널리 사용되는 내부 API의 변경사항
- 플래그 및 명령줄 인터페이스가 변경되었습니다.
디자인 검토 이유
설계 문서를 작성할 때는 다른 Bazel 개발자와 협의하고 Bazel 핵심팀의 안내를 받을 수 있습니다. 예를 들어 제안서에서 BUILD, WORKSPACE 또는 bzl 파일에서 사용할 수 있는 함수나 객체를 추가, 삭제 또는 수정하는 경우 Starlark팀을 검토자로 추가합니다. 설계 문서를 제출하기 전에 검토하는 이유는 다음과 같습니다.
- Bazel은 매우 복잡한 시스템입니다. 겉보기에는 무해해 보이는 로컬 변경사항이 전 세계적으로 상당한 영향을 미칠 수 있습니다.
- 이 팀에는 사용자로부터 많은 기능 요청이 접수됩니다. 이러한 요청은 기술적 타당성뿐만 아니라 다른 기능 요청과 관련한 중요도도 고려하여 평가되어야 합니다.
- Bazel 기능은 핵심 팀 외부의 사람들이 자주 구현하는데, 이러한 참여자는 Bazel 전문 지식 수준이 매우 다양합니다.
- Bazel 팀 자체는 다양한 수준의 전문성을 갖추고 있습니다. 팀 구성원이 Bazel의 모든 부분을 완벽하게 이해하지는 못합니다.
- Bazel 변경사항은 이전 버전과의 호환성을 고려하고 브레이킹 체인지를 방지해야 합니다.
Bazel의 디자인 검토 정책은 다음과 같은 가능성을 극대화하는 데 도움이 됩니다.
- 모든 기능 요청은 기준 수준의 정밀 조사를 받습니다.
- 제대로 작동하지 않을 수 있는 구현에 투자하기 전에 적합한 사람들이 설계에 주의를 기울일 것입니다.
시작하는 데 도움이 되도록 Bazel 제안서 저장소의 설계 문서를 살펴보세요. 설계가 진행 중이므로 구현 세부정보는 시간이 지남에 따라 의견과 함께 변경될 수 있습니다. 게시된 설계 문서는 초기 설계를 보여주며 디자인 구현 시 진행 중인 변경사항은 캡처하지 않습니다. 현재 Bazel 기능에 관한 설명은 항상 문서를 참고하세요.
참여자 워크플로
기여자는 설계 문서를 작성하고, pull 요청을 보내고, 제안에 대한 검토자를 요청할 수 있습니다.
디자인 문서 작성
모든 설계 문서에는 다음을 포함하는 헤더가 있어야 합니다.
- author
- 마지막 주요 변경 날짜
- 검토자 목록 (리드 검토자 한 명만 포함)
- 현재 상태 (초안, 검토 중, 승인됨, 거부됨, 구현 중, 구현됨)
- 토론 대화목록 링크 (공지사항 이후 추가 예정)
이 문서는 누구나 읽을 수 있는 Google 문서로 작성하거나 마크다운을 사용할 수 있습니다. 마크다운 / Google 문서 비교는 아래에서 확인하세요.
사용자에게 미치는 영향이 있는 제안서에는 이전 버전과의 호환성에 미치는 영향을 설명하는 섹션이 있어야 합니다 (필요한 경우 출시 계획).
pull 요청 만들기
문서를 디자인 색인에 추가하는 pull 요청 (PR)을 만들어 디자인 문서를 공유합니다. 마크다운 파일 또는 문서 링크를 PR에 추가합니다.
가능하다면 리드 검토자를 선택하고 다른 검토자를 참조에 포함합니다. 수석 검토자를 선택하지 않으면 Bazel 유지관리 담당자가 PR에 검토자를 할당합니다.
PR을 만든 후 검토자는 코드 검토 중에 예비 댓글을 작성할 수 있습니다. 예를 들어 수석 검토자는 추가 검토자를 제안하거나 누락된 정보를 지적할 수 있습니다. 수석 검토자는 검토 프로세스를 시작할 수 있다고 생각할 때 PR을 승인합니다. 그렇다고 해서 제안이 완벽하거나 승인된다는 것은 아닙니다. 제안에 논의를 시작하기에 충분한 정보가 포함되어 있다는 의미입니다.
새 제안 발표
PR이 제출되면 bazel-dev에 공지를 보냅니다.
다른 그룹 (예: bazel-discuss)을 복사하여 Bazel 최종 사용자의 의견을 받을 수도 있습니다.
검토자와 반복
관심 있는 누구나 제안서에 댓글을 달 수 있습니다. 질문에 답하고, 제안을 명확히 하며, 우려사항을 해결하도록 노력하세요
토론은 공지 대화목록에서 진행해야 합니다. 제안이 Google 문서에 있는 경우 댓글을 대신 사용할 수 있습니다 (익명 댓글 허용됨).
상태 업데이트
반복이 완료되면 새 PR을 만들어 제안서 상태를 업데이트합니다. PR을 동일한 리드 검토자에게 전송하고 다른 검토자를 참조에 포함합니다.
제안서를 공식적으로 수락하려면 선임 검토자가 다른 검토자가 결정에 동의하는지 확인한 후 PR을 승인합니다.
첫 번째 공지 후 제안서가 승인되기까지 최소 1주일이 있어야 합니다. 이렇게 하면 사용자가 충분한 시간을 들여 문서를 읽고 우려사항을 공유할 수 있습니다.
제안이 수락되기 전에 개념 증명이나 실험 등으로 구현을 시작할 수 있습니다. 그러나 검토가 완료되기 전에는 변경사항을 제출할 수 없습니다.
리드 검토자 선정
수석 검토자는 다음에 해당하는 도메인 전문가여야 합니다.
- 관련 하위 시스템에 대한 지식
- 객관적이고 건설적인 피드백을 제공할 수 있음
- 전체 검토 기간 동안 절차를 진행할 수 있습니다.
다양한 팀 라벨의 연락처를 확인하는 것이 좋습니다.
마크다운과 Google Docs
둘 다 수락되므로 가장 적합한 방법을 결정하세요.
Google Docs의 이점:
- 간편하게 시작할 수 있으므로 브레인스토밍에 효과적입니다.
- 공동 편집
- 빠른 반복.
- 수정을 제안하는 간편한 방법입니다.
마크다운 파일 사용의 이점:
- 연결을 위한 URL 정리
- 버전에 대한 명시적인 기록입니다.
- 링크를 공개하기 전에 액세스 권한을 설정하는 것을 잊지 마세요.
- 검색엔진으로 쉽게 검색할 수 있습니다.
- 미래에도 활용 가능: 일반 텍스트는 특정 도구에 적용되지 않으며 인터넷 연결이 필요하지 않습니다.
- 작성자가 더 이상 없으면 업데이트할 수 있습니다.
- 자동으로 처리될 수 있습니다 (더 이상 작동하지 않는 링크 업데이트/감지, 작성자 목록 가져오기 등).
먼저 Google 문서를 반복한 다음 나중에 사용할 수 있도록 마크다운으로 변환할 수 있습니다.
Google Docs 사용
일관성을 위해 Bazel 디자인 문서 템플릿을 사용합니다. 필요한 헤더가 포함되어 있으며 다른 Bazel 관련 문서와 시각적 일관성을 만듭니다. 그렇게 하려면 File > Make a copy를 클릭하거나 이 링크를 클릭하여 디자인 문서 템플릿의 사본을 만듭니다.
누구나 문서를 읽을 수 있도록 하려면 공유 > 고급 > 변경...을 클릭하고 '사용 - 링크가 있는 모든 사용자'를 선택합니다. 문서에 댓글을 허용하면 Google 계정이 없어도 누구나 익명으로 댓글을 쓸 수 있습니다.
마크다운 사용
문서는 GitHub에 저장되며 마크다운의 GitHub 버전(사양)을 사용합니다.
PR을 생성하여 기존 문서를 업데이트합니다. 중요한 변경사항은 문서 검토자가 검토해야 합니다. 사소한 변경 (오타, 서식 등)은 누구나 승인할 수 있습니다.
검토자 워크플로
검토자는 설계 문서에 코멘트를 달고, 검토하고, 승인합니다.
일반적인 검토자의 책임
디자인 문서를 검토하고, 필요한 경우 추가 정보를 요청하며, 검토 프로세스를 통과한 설계를 승인하는 책임은 개발자에게 있습니다.
새로운 제안을 받는 경우
- 문서를 빠르게 살펴봅니다.
- 중요한 정보가 누락되었거나 설계가 프로젝트 목표에 맞지 않는 경우에 설명합니다.
- 추가 검토자를 추천합니다.
- 검토 준비가 완료되면 PR을 승인합니다.
검토 절차 중
- 문제가 있거나 설명이 필요한 문제에 관해 디자인 작성자와 대화를 나눕니다.
- 적절한 경우 설계에 대해 알고 있어야 하는 비검토자의 의견을 받습니다.
- 승인 전제 조건으로 작성자가 처리해야 하는 의견을 결정합니다.
- 제안의 현재 상태가 만족스러우면 토론 대화목록에 'LGTM' (Looks Good To Me)을 작성합니다.
모든 디자인 검토 요청에 대해 이 절차를 따르세요. Bazel에 영향을 주는 설계가 설계 색인에 포함되어 있지 않다면 승인하지 마세요.
리드 평가자의 책임
대기 중인 설계의 구현에 관한 결정은 개발자에게 있습니다. 이렇게 할 수 없는 경우 적합한 대리자를 식별 (PR을 대리자에게 재할당)하거나 추가 처리를 위해 버그를 Bazel 관리자에게 재할당해야 합니다.
검토 절차 중
- 의견 및 디자인 반복 프로세스가 건설적으로 진행되도록 합니다.
- 승인하기 전에 다른 검토자의 우려사항이 해결되었는지 확인합니다.
모든 검토자의 승인 후
- 메일링 리스트에 공지한 후 최소 1주일이 있어야 합니다.
- PR에서 상태를 업데이트해야 합니다.
- 제안서 작성자가 보낸 PR을 승인합니다.
디자인 거부
- PR 작성자가 PR을 보냈는지 확인하거나 PR을 보냅니다.
- PR에서 문서의 상태를 업데이트합니다.
- 현재 상태에서 디자인을 승인할 수 없는 이유를 설명하고, 다음 단계 (예: '잘못된 가정을 다시 확인하고 다시 제출')를 설명하는 메모를 문서에 추가합니다.