Bazel에 브레이킹 체인지를 적용하는 것은 불가피합니다. 우리는 디자인을 변경하고 제대로 작동하지 않는 부분을 고쳐야 합니다. 그러나 커뮤니티 및 Bazel 생태계가 따라올 수 있도록 했습니다. 이를 위해 Bazel 프로젝트는 이전 버전과의 호환성 정책을 따라야 합니다. 이 문서에서는 Bazel 기여자가 브레이킹 체인지를 만드는 프로세스를 설명합니다. 정책을 준수하도록 변경할 수 없습니다.
GitHub 문제
GitHub 문제 제출 Bazel 저장소에서 찾을 수 있습니다 예시 보기
다음과 같이 하시기 바랍니다.
제목은 플래그의 이름으로 시작합니다 (플래그 이름은
incompatible_)을 입력합니다.라벨 추가
incompatible-change설명에는 변경사항에 대한 설명과 설계 문서를 참조하세요
설명에는 사용자에게 이전 방법을 설명하는 이전 레시피가 포함되어 있습니다. 코드를 업데이트해야 합니다. 기계적인 변경인 경우 마이그레이션 도구를 사용할 수 있습니다.
설명에 다음과 같은 경우 사용자에게 표시되는 오류 메시지의 예가 포함됩니다. 마이그레이션되지 않습니다 이렇게 하면 다음 위치에서 GitHub 문제를 더 쉽게 찾을 수 있습니다. 있습니다. 오류 메시지가 유용하고 실행 가능한지 확인합니다. 가능한 경우 오류 메시지에는 호환되지 않는 광고 항목의 이름이 포함되어야 합니다. 플래그.
이전 도구의 경우
Buildifier.
BUILD, WORKSPACE, .bzl 파일에 자동 수정사항을 적용할 수 있습니다.
또한 경고가 보고될 수도 있습니다.
구현
Bazel에서 새 플래그를 만듭니다. 기본값은 false여야 합니다. 도움말 텍스트
GitHub 문제의 URL이 포함되어야 합니다. 플래그 이름이
incompatible_, 다음과 같은 메타데이터 태그가 필요합니다.
metadataTags = {
OptionMetadataTag.INCOMPATIBLE_CHANGE,
},
커밋 설명에 플래그에 대한 간략한 요약을 추가합니다.
또한 다음 형식으로 RELNOTES:를 추가합니다.
RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details
커밋은 관련 문서도 업데이트해야 하므로 코드가 문서와 일치하지 않는 커밋 기간 Google의 문서의 버전이 지정되므로 문서에 대한 변경사항이 의도치 않게 적용되지 않습니다. 있습니다
라벨
커밋이 병합되고 호환되지 않는 변경사항을 적용할 준비가 되면 라벨을 추가합니다.
migration-ready 드림
를 참조하세요.
플래그에서 문제가 발견되고 사용자가 아직 이전할 것으로 예상되지 않는 경우:
migration-ready 플래그를 삭제합니다.
다음 메이저 버전에서 플래그를 바꿀 계획이라면 `breaking-change-X.0" 라벨을 추가합니다. 전달할 수 있습니다
저장소 업데이트
Bazel CI는
Bazel@HEAD + 다운스트림 대부분은 보통
종속 항목을 이전해야 합니다. 이러한 프로젝트의 마이그레이션 상태를 모니터링하려면 bazelisk-plus-incompatible-flags 파이프라인을 사용하면 됩니다.
여기에서 이 파이프라인의 작동 방식을 확인하세요.
Google 개발 지원팀에서는 migration-ready 라벨을 모니터링합니다. 이 라벨을 GitHub 문제에 추가하면 다음 작업이 처리됩니다.
GitHub 문제에 의견을 작성하여 이전해야 하는 실패 및 다운스트림 프로젝트의 목록을 추적합니다 (예시 참조).
GitHub 문제를 제출하여 호환되지 않는 변경사항으로 인해 손상된 모든 다운스트림 프로젝트의 소유자에게 알립니다 (예시 참조).
목표 출시일 전에 모든 문제가 해결되었는지 후속 조치를 취합니다.
호환되지 않는 변경 작성자가 다운스트림 파이프라인에서 프로젝트를 마이그레이션하는 데 전적으로 책임이 있는 것은 아니지만, 마이그레이션을 가속화하고 Bazel 사용자와 Bazel Green팀 모두의 작업을 더 쉽게 하기 위해 다음을 수행할 수 있습니다.
다운스트림 프로젝트를 수정하기 위해 PR을 전송합니다.
마이그레이션에 대한 도움이 필요하면 Bazel 커뮤니티에 문의하세요 (예: Bazel Rules Authors SIG).
깃발 던지기
플래그의 기본값을 true로 전환하기 전에 다음을 확인하세요.
생태계의 핵심 저장소가 마이그레이션됩니다.
bazelisk-plus-incompatible-flags파이프라인에서 플래그는The following flags didn't break any passing Bazel team owned/co-owned projects아래에 표시되어야 합니다.체크리스트의 모든 문제가 해결됨/종료됨으로 표시됩니다.
사용자의 우려 사항과 질문이 해결되었습니다.
Bazel에서는 플래그를 뒤집을 준비가 되었지만 Google의 내부 이전에서는 차단된 경우 내부 blazerc 파일에서 플래그 값을 false로 설정하여 플래그 바꾸기를 차단 해제하는 것이 좋습니다. 이렇게 하면 Bazel 사용자가 최대한 빨리 새 동작에 기본적으로 의존하도록 할 수 있습니다.
플래그 기본값을 true로 변경하는 경우:
- 커밋 설명에
RELNOTES[INC]을 사용합니다. 다음 형식을 따릅니다.RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details커밋의 나머지 설명에 추가 정보를 포함할 수 있습니다. - GitHub 문제를 종료하도록 설명에
Fixes #xyz을 사용합니다. 커밋이 병합될 때 - 필요한 경우 문서를 검토하고 업데이트합니다.
- 플래그 삭제를 추적하려면 새 문제
#abc을 제출합니다.
플래그 삭제
HEAD에서 플래그가 뒤집어지면 결국 Bazel에서 삭제됩니다. 호환되지 않는 플래그를 삭제하려는 경우:
- 호환되지 않는 주요 변경사항인 경우 사용자가 이전할 시간을 더 많이 확보하는 것이 좋습니다. 이 플래그는 하나 이상의 주 버전에서 제공하는 것이 이상적입니다.
- 플래그를 삭제하는 커밋의 경우 설명에
Fixes #abc을 사용합니다. 커밋이 병합되면 GitHub 문제가 종료됩니다.