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