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
커밋은 관련 문서도 업데이트해야 하므로 코드와 문서가 일치하지 않는 커밋 윈도가 없어야 합니다. 문서에는 버전이 지정되어 있으므로 문서 변경사항이 실수로 조기에 출시되지 않습니다.
라벨
커밋이 병합되고 호환되지 않는 변경사항을 채택할 준비가 되면 GitHub 문제에 migration-ready 라벨을 추가합니다.
플래그에 문제가 있고 사용자가 아직 이전하지 않아야 하는 경우 migration-ready 플래그를 삭제합니다.
다음 주요 버전에서 플래그를 전환할 계획이라면 문제에 `breaking-change-X.0` 라벨을 추가하세요.
저장소 업데이트
Bazel CI는 Bazel@HEAD + 다운스트림에서 중요한 프로젝트 목록을 테스트합니다. 대부분 다른 Bazel 프로젝트의 종속 항목인 경우가 많으므로 더 광범위한 커뮤니티의 마이그레이션을 차단 해제하기 위해 마이그레이션하는 것이 중요합니다. 이러한 프로젝트의 이전 상태를 모니터링하려면 bazelisk-plus-incompatible-flags 파이프라인을 사용하면 됩니다.
이 파이프라인의 작동 방식은 여기를 참고하세요.
개발 지원팀에서 migration-ready 라벨을 모니터링합니다. 이 라벨을 GitHub 문제에 추가하면 다음 사항이 처리됩니다.
GitHub 문제에 댓글을 만들어 실패 목록과 이전해야 하는 다운스트림 프로젝트를 추적합니다 (예시 참고).
비호환 변경사항으로 인해 다운스트림 프로젝트가 중단된 모든 소유자에게 알리도록 GitHub 문제를 신고합니다 (예 참고).
타겟 출시일 전에 모든 문제가 해결되었는지 확인하기 위해 후속 조치 취하기
다운스트림 파이프라인에서 프로젝트를 이전하는 것은 호환되지 않는 변경사항 작성자의 책임이 전적으로 아니지만, 다음을 수행하여 이전을 가속화하고 Bazel 사용자와 Bazel Green Team 모두의 작업을 더 쉽게 할 수 있습니다.
다운스트림 프로젝트를 수정하는 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에서 삭제해야 합니다. 호환되지 않는 플래그를 삭제할 계획인 경우 다음을 확인하세요.
- 호환되지 않는 주요 변경사항인 경우 사용자가 이전할 수 있는 시간을 더 많이 두는 것이 좋습니다. 플래그는 하나 이상의 주요 버전에서 사용할 수 있어야 합니다.
- 플래그를 삭제하는 커밋의 경우 커밋이 병합될 때 GitHub 문제가 닫히도록 설명에
Fixes #abc를 사용하세요.