BazelCon 2022는 11월 16~17일에 뉴욕과 온라인에서 개최됩니다.
지금 등록하기

디자인 문서

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

사용자 대상 기능을 추가, 변경 또는 삭제하거나중요한 아키텍처 변경사항 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 기능에 대한 설명을 참조하세요.

Contributor 워크플로

도움을 주신 분들은 디자인 문서를 작성하고 pull 요청을 보내 제안서에 대한 검토자를 요청하시면 됩니다.

디자인 문서 작성

모든 디자인 문서에는 다음을 포함하는 헤더가 있어야 합니다.

  • 작가
  • 마지막 주요 변경일
  • 리드 검토자 (1명)를 포함한 리뷰 작성자 목록
  • 현재 상태 (초안, 검토 중, 승인됨, 거부됨 ,구현 중, 구현됨 ).
  • 토론 대화목록 링크 (공지사항 이후 추가됨)

문서는 누구나 읽을 수 있는 Google 문서로 또는 마크다운을 사용하여 작성할 수 있습니다. 아래에서 마크다운 / Google Docs 비교를 참조하세요.

사용자에게 눈에 보이는 영향을 미치는 제안서에는 이전 버전과의 호환성에 대한 영향을 설명하는 섹션이 있어야 합니다 (필요한 경우 출시 계획).

pull 요청 만들기

문서를 디자인 색인에 추가하는 pull 요청 (PR)을 만들어 디자인 문서를 공유합니다. 마크다운 파일 또는 문서 링크를 PR에 추가합니다.

가능하면 리드 검토자를 선택하고 다른 검토자를 참조에 포함하세요. 리드 검토자를 선택하지 않으면 Bazel 운영자가 PR에 검토자를 할당합니다.

PR을 만들면 검토자가 코드 검토 중에 예비 댓글을 작성할 수 있습니다. 예를 들어 리드 검토자는 추가 검토자를 제안하거나 누락된 정보를 표시할 수 있습니다. 리드 검토자가 검토 프로세스를 시작할 수 있다고 판단하면 PR을 승인합니다. 그렇다고 해서 제안서가 완벽하거나 승인되는 것은 아닙니다. 제안서에 토론을 시작하기에 충분한 정보가 포함되어 있다는 의미입니다.

새 제안서 공지

PR이 제출되면 bazel-dev에 공지를 보냅니다.

다른 그룹 (예: bazel-discuss)을 복사하여 Bazel 최종 사용자로부터 의견을 받을 수 있습니다.

검토자와 반복

관심 있는 사용자 모두 제안에 댓글을 달 수 있습니다. 질문에 답하고, 제안서를 명확하게 설명하고, 우려사항을 해결합니다.

공지사항 대화목록에 논의해야 합니다. 제안이 Google 문서에 있는 경우 주석이 대신 사용될 수 있습니다 (익명 주석은 허용됨).

상태 업데이트

반복이 완료되면 새 PR을 만들어 제안서 상태를 업데이트합니다. PR을 동일한 리드 평가자에게 보내고 다른 검토자를 참조에 포함합니다.

다른 검토자가 결정에 동의할 수 있도록 리드 검토자가 PR을 승인하여 공식적으로 제안서를 수락합니다.

첫 번째 공지와 제안서 승인 사이에 최소 1주일이 있어야 합니다. 이렇게 하면 사용자가 문서를 읽고 우려사항을 공유할 시간을 가질 수 있습니다.

개념 증명 또는 실험 등으로 제안서가 수락되기 전에 구현을 시작할 수 있습니다. 하지만 검토가 완료되기 전에는 변경사항을 제출할 수 없습니다.

리드 검토자 선택

리드 검토자는 다음과 같은 도메인 전문가여야 합니다.

  • 관련 하위 시스템을 잘 알고 있음
  • 객관적이며 건설적인 피드백을 제공할 수 있습니다.
  • 전체 검토 기간 동안 프로세스 진행 가능

다양한 팀 라벨의 연락처를 확인하는 것이 좋습니다.

마크다운 및 Google Docs도구

둘 다 허용되므로 가장 적합한 옵션을 선택하세요.

Google 문서 사용의 이점:

  • 쉽게 시작할 수 있으므로 브레인스토밍에 효과적입니다.
  • 공동작업 수정
  • 빠른 반복입니다.
  • 수정을 제안하는 손쉬운 방법

마크다운 파일 사용의 이점:

  • 연결을 위해 URL을 정리합니다.
  • 버전의 명시적 레코드입니다.
  • 링크를 공개하기 전에 액세스 권한을 설정하는 것을 잊지 마세요.
  • 검색엔진을 통해 쉽게 검색할 수 있습니다.
  • 미래 경쟁력: 일반 텍스트는 지장이 없는 도구이기 때문에 인터넷 연결이 필요하지 않습니다.
  • 작성자가 더 이상 사용되지 않더라도 업데이트할 수 있습니다.
  • 이러한 링크는 자동으로 처리될 수 있습니다 (데드 링크 업데이트/감지, 작성자 목록 가져오기 등).

먼저 Google 문서에서 반복한 후 후반부에 맞게 마크다운으로 변환할 수 있습니다.

Google 문서 사용

일관성을 위해 Bazel 디자인 문서 템플릿을 사용하세요. 필요한 헤더를 포함하고 다른 Bazel 관련 문서와의 시각적 일관성을 생성합니다. 이렇게 하려면 파일 > 사본 만들기를 클릭하거나 이 링크를 클릭하여 디자인 문서 템플릿 사본을 만듭니다.

문서를 누구나 읽을 수 있도록 하려면 공유 > 고급 > 변경...을 클릭한 후 '사용 - 링크가 있는 모든 사용자' 문서에 댓글을 허용하면 Google 계정이 없어도 누구나 익명으로 댓글을 달 수 있습니다.

마크다운 사용

문서는 GitHub에 저장되며 GitHub 버전의 마크다운(사양)을 사용합니다.

PR을 만들어 기존 문서를 업데이트합니다. 중요한 변경사항은 문서 검토자가 검토해야 합니다. 사소한 변경사항 (예: 오타, 형식 지정)은 누구나 승인할 수 있습니다.

리뷰 작성자 워크플로

검토자가 디자인 문서를 댓글, 검토, 승인합니다.

일반적인 검토자의 책임

개발자는 설계 문서를 검토하고 필요한 경우 추가 정보를 요청하며 검토 프로세스를 통과하는 설계를 승인해야 합니다.

새 제안서를 받는 경우

  1. 문서를 빠르게 살펴보겠습니다.
  2. 중요한 정보가 누락되었거나 설계가 프로젝트의 목표에 부합하지 않는 경우 의견을 제공합니다.
  3. 추가 검토자를 제안합니다.
  4. 검토할 준비가 되면 PR을 승인합니다.

검토 과정에서

  1. 문제가 있거나 설명이 필요한 문제에 관해 디자인 작성자와 대화를 나 니다.
  2. 가능하다면 디자인을 잘 알고 있어야 하는 평가자가 아닌 사람의 의견을 초대합니다.
  3. 승인을 위해 전제 조건으로 작성자가 처리해야 할 댓글을 결정합니다.
  4. 제안서의 현재 상태가 만족스러우면 토론 대화목록에 'LGTM' (Looks Good To Me)을 입력합니다.

모든 디자인 검토 요청에 대해 이 절차를 따릅니다. Bazel에 영향을 주는 설계가 디자인 색인에 포함되어 있지 않다면 승인하지 마세요.

리드 검토자의 책임

개발자는 대기 중인 디자인의 구현에 관한 go / go-go 결정을 내릴 책임이 있습니다. 이 작업을 할 수 없다면 적절한 위임을 확인하거나 (PR을 대리자에게 다시 할당) Bazel 관리자에게 버그를 재할당하여 추가 처리를 해야 합니다.

검토 과정에서

  1. 주석 및 설계 반복 프로세스가 계속해서 진행되어야 합니다.
  2. 승인 전에 다른 검토자의 우려사항이 해결되었는지 확인하세요.

모든 검토자의 승인 후

  1. 메일링 리스트의 공지사항 이후 1주일 이상 지났는지 확인합니다.
  2. PR이 상태를 업데이트해야 합니다.
  3. 제안서 작성자가 보낸 PR을 승인합니다.

거부되는 디자인

  1. PR 작성자가 PR을 보내는지 확인합니다. 또는 PR을 보낼 수 있습니다.
  2. PR은 문서 상태를 업데이트합니다.
  3. 문서에 설계를 현재 상태로 승인할 수 없는 이유를 설명하고 다음 단계 (예: '잘못된 가정 재검토 및 다시 제출')에 대한 설명을 추가합니다.