디자인 문서

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

사용자 대면 기능을 추가, 변경 또는 삭제하거나 Bazel에 아키텍처를 대대적으로 변경할 계획이라면 변경사항을 제출하기 전에 디자인 문서를 작성하고 검토를 받아야 합니다.

다음은 중요한 변경사항의 예입니다.

  • 네이티브 빌드 규칙 추가 또는 삭제
  • 네이티브 규칙 브레이킹 체인지
  • 둘 이상의 규칙 동작에 영향을 미치는 네이티브 빌드 규칙 의미 체계 변경사항
  • Bazel의 규칙 정의 API 변경사항
  • Bazel이 다른 시스템에 연결하는 데 사용하는 API의 변경사항
  • Starlark 언어, 시맨틱스 또는 API의 변경사항
  • Bazel 성능 또는 메모리 사용에 광범위한 영향을 미칠 수 있는 변경사항 (더 좋거나 나쁨)
  • 널리 사용되는 내부 API의 변경사항
  • 플래그 및 명령줄 인터페이스 변경사항

디자인 검토를 사용하는 이유

설계 문서를 작성할 때는 다른 Bazel 개발자와 협업하고 Bazel의 핵심 팀에 조언을 받을 수 있습니다. 예를 들어 제안서에서 BUILD, WORKSPACE 또는 bzl 파일에 제공되는 함수나 객체를 추가, 삭제 또는 수정하는 경우 Starlark팀을 검토자로 추가하세요. 설계 문서는 다음과 같은 이유로 제출 전에 검토됩니다.

  • Bazel은 매우 복잡한 시스템입니다. 무해한 로컬 변경사항이 전 세계에 상당한 영향을 미칠 수 있습니다.
  • 팀에서는 사용자에게 여러 기능 요청을 받습니다. 이러한 요청의 기술적 실행 가능성뿐 아니라 다른 기능 요청과 관련된 중요성도 평가해야 합니다.
  • Bazel 기능은 핵심 팀 외부의 사용자가 자주 구현합니다. 이러한 기여자에는 Bazel 전문성의 수준이 매우 다양합니다.
  • Bazel 팀 자체에는 다양한 수준의 전문성이 있습니다. Bazel의 모든 부분을 완전히 이해하는 단일 팀원은 없습니다.
  • Bazel에 대한 변경사항은 이전 버전과의 호환성을 고려해야 하며 변경사항이 손상되지 않도록 해야 합니다.

Bazel의 설계 검토 정책은 다음과 같은 가능성을 극대화하는 데 도움이 됩니다.

  • 모든 기능 요청에 대한 조사가 기준 수준으로 이루어집니다.
  • 제대로 작동하지 않을 수 있는 구현에 투자하기 전에 적절한 설계 방안을 고려하게 됩니다

시작하는 데 도움이 되도록 Bazel 제안서 저장소에서 설계 문서를 살펴보세요. 설계는 현재 진행 중이므로 시간이 지남에 따라 구현과 피드백에 따라 구현 세부정보가 변경될 수 있습니다. 게시된 디자인 문서는 초기 디자인을 캡처하며, 디자인이 구현될 때 진행 중인 변경사항은 포함하지 않습니다. 항상 현재 Bazel 기능에 대한 설명을 보려면 문서를 참조하세요.

참여자 워크플로

기여자는 설계 문서를 작성하고 pull 요청을 보내고 제안서에 검토자를 요청할 수 있습니다.

디자인 문서 작성

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

  • 작성자
  • 마지막 주요 변경 날짜
  • 리드 검토자 한 명만 포함된 검토자 목록
  • 현재 상태(초안, 검토 중, 승인됨, 거부됨, 구현됨, 구현됨)
  • 토론 대화목록 링크(공지사항 추가 예정)

문서는 누구나 읽을 수 있는 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 Docs를 사용할 때의 이점:

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

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

  • 연결을 위해 URL을 정리합니다.
  • 버전의 명시적 레코드
  • 링크를 게시하기 전에 액세스 권한을 설정해야 합니다.
  • 검색엔진을 통해 쉽게 검색할 수 있습니다.
  • 미래에 대비: 일반 도구는 특정 도구와 무관하며 인터넷 연결이 필요하지 않습니다.
  • 작성자가 더 이상 근처에 있지 않은 경우에도 이를 업데이트할 수 있습니다.
  • 자동으로 처리할 수 있습니다 (작동하지 않는 링크 업데이트/감지, 작성자 목록 가져오기 등).

먼저 Google 문서에서 반복한 다음 후기를 위해 마크다운으로 변환할 수 있습니다.

Google Docs 사용

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

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

마크다운 사용

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

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

검토자 워크플로

검토자가 디자인 문서에 댓글을 달고, 검토하고, 승인합니다.

일반적인 검토자의 책임

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

새 제안서를 받으면

  1. 문서를 빠르게 살펴보세요.
  2. 중요한 정보가 누락되었거나 디자인이 프로젝트의 목표에 맞지 않으면 댓글을 답니다.
  3. 추가 검토자를 제안합니다.
  4. 검토 준비가 완료되면 PR을 승인합니다.

검토 프로세스 중

  1. 문제가 있거나 명확한 설명이 필요한 문제에 관해 설계 작성자와 대화합니다.
  2. 적절한 경우 설계를 알고 있어야 하는 비검토자의 의견을 초대합니다.
  3. 승인의 기본 요건으로 작성자가 처리해야 하는 의견을 결정합니다.
  4. 제안서의 현재 상태에 만족하면 토론 대화목록에 'LGTM'(Looks Good To Me)을 입력합니다.

모든 디자인 검토 요청에 이 절차를 따릅니다. 디자인 색인에 없는 경우 Bazel에 영향을 미치는 설계를 승인하지 마세요.

리드 검토자의 책임

대기 중인 설계의 구현과 관련하여 이동 여부를 결정할 책임은 개발자에게 있습니다. 이 작업을 할 수 없으면 적절한 위임을 식별 (대리자에게 PR을 재할당)하거나 추가 처리를 위해 Bazel 관리자에게 버그를 재할당해야 합니다.

검토 프로세스 중

  1. 댓글 및 디자인 반복 프로세스가 발전하도록 만드세요.
  2. 승인 전에 다른 검토자의 우려사항이 해결되었는지 확인합니다.

모든 검토자의 승인 후

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

디자인 거부

  1. PR 작가가 PR을 보내거나 PR을 보내세요.
  2. PR이 문서의 상태를 업데이트합니다.
  3. 현재 상태에서 디자인을 승인할 수 없는 이유와 '잘못된 가정을 다시 제출하고 다시 제출'하는 경우 다음 단계를 설명하는 문서에 설명을 추가합니다.