Bazel에 브레이킹 체인지를 적용해야 합니다. 디자인을 변경하고 제대로 작동하지 않는 부분을 수정해야 합니다. 그러나 커뮤니티 및 Bazel 생태계가 이를 따를 수 있도록 해야 합니다. 이를 위해 Bazel 프로젝트는 이전 버전과의 호환성 정책을 채택했습니다. 이 문서에서는 Bazel 참여자가 Bazel에서 이 정책을 준수하도록 브레이킹 체인지를 적용하는 프로세스를 설명합니다.
GitHub 문제
Bazel 저장소에 GitHub 문제를 제출합니다. 예시 보기
다음과 같이 하는 것이 좋습니다.
제목은 플래그 이름으로 시작합니다 (플래그 이름은
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
또한 커밋이 관련 문서를 업데이트하여 코드가 문서와 일치하지 않는 커밋 기간이 없도록 해야 합니다. 문서에 버전이 지정되었으므로 문서의 변경사항이 의도치 않게 조기에 출시되지 않습니다.
라벨
커밋이 병합되고 호환되지 않는 변경사항을 적용할 준비가 되면 migration-ready 라벨을 GitHub 문제에 추가합니다.
플래그에서 문제가 발견되었고 사용자가 아직 이전하지 않는 경우 migration-ready 플래그를 삭제합니다.
다음 메이저 버전에서 플래그를 뒤집으려면 'breaking-change-X.0' 라벨을 문제에 추가합니다.
저장소 업데이트
Bazel CI는 Bazel@HEAD + Downstream에서 중요한 프로젝트 목록을 테스트합니다. 대부분은 다른 Bazel 프로젝트의 종속 항목인 경우가 많으므로 광범위한 커뮤니티에서 마이그레이션을 차단 해제하려면 해당 프로젝트를 이전하는 것이 중요합니다. 이러한 프로젝트의 마이그레이션 상태를 모니터링하려면 bazelisk-plus-incompatible-flags 파이프라인을 사용하면 됩니다.
여기에서 이 파이프라인의 작동 방식을 확인하세요.
개발 지원팀에서 migration-ready 라벨을 모니터링합니다. 이 라벨을 GitHub 문제에 추가하면 다음 문제를 처리합니다.
GitHub 문제에서 댓글을 만들어 이전해야 하는 실패 목록 및 다운스트림 프로젝트를 추적합니다(예시 참고).
호환되지 않는 변경사항으로 인해 손상된 모든 다운스트림 프로젝트의 소유자에게 알림을 보내려면 GitHub 문제를 신고하세요(예 보기).
후속 조치를 통해 목표 출시일 전에 모든 문제가 해결되었는지 확인
다운스트림 파이프라인에서 프로젝트 마이그레이션이 완전히 호환되지 않는 변경 작성자의 책임은 아니지만 다음 작업을 수행하여 Bazel 사용자와 Bazel 그린 팀의 마이그레이션 속도를 높이고 작업을 간소화할 수 있습니다.
다운스트림 프로젝트를 수정하기 위해 PR을 보냅니다.
이전에 대한 도움을 받으려면 Bazel 커뮤니티에 문의하세요 (예: Bazel 규칙 작성자 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나머지 커밋 설명에 추가 정보를 포함할 수 있습니다. - 설명에서
Fixes #xyz을 사용하여 커밋이 병합될 때 GitHub 문제가 종료되도록 합니다. - 문서를 검토하고 필요한 경우 업데이트합니다.
- 새로운 문제
#abc를 신고하여 플래그 삭제를 추적합니다.
플래그 삭제
플래그는 HEAD에서 뒤집히고 최종적으로 Bazel에서 삭제해야 합니다. 호환되지 않는 플래그를 삭제하려고 하는 경우:
- 호환되지 않는 중요한 변경사항인 경우 사용자가 이전할 시간을 더 많이 확보하는 것이 좋습니다. 하나 이상의 메이저 버전에서 플래그를 사용할 수 있는 것이 좋습니다.
- 플래그를 삭제하는 커밋의 경우 설명에서
Fixes #abc를 사용하여 커밋이 병합될 때 GitHub 문제가 종료되도록 합니다.