이 문서는 Bazel 기여자를 대상으로 합니다.
Bazel의 커밋 설명에는 RELNOTES: 태그와 출시 노트가 포함됩니다. 이 태그는 Bazel팀에서 각 출시의 변경사항을 추적하고 출시 공지를 작성하는 데 사용됩니다.
개요
변경사항이 버그 수정인가요? 그렇다면 출시 노트가 필요하지 않습니다. GitHub 문제에 대한 참조를 포함하세요.
변경사항이 사용자에게 표시되는 방식으로 Bazel을 추가 / 삭제 / 변경하는 경우 이를 언급하는 것이 좋습니다.
변경사항이 중요한 경우 먼저 설계 문서 정책을 따르세요.
가이드라인
출시 노트는 사용자가 읽으므로 짧고 (이상적으로 한 문장), 전문 용어 (Bazel 내부 용어)를 피하고, 변경사항의 내용에 중점을 두어야 합니다.
관련 문서 링크를 포함합니다. 거의 모든 출시 노트에는 링크가 포함되어야 합니다. 설명에 플래그, 기능, 명령어 이름이 언급되어 있으면 사용자는 이에 관해 자세히 알고 싶어 할 것입니다.
코드, 기호, 플래그 또는 밑줄이 포함된 단어는 백틱으로 묶습니다.
버그 설명을 복사하여 붙여넣지 마세요. 버그 설명은 종종 이해하기 어렵고 Google 직원에게만 의미가 있으며 사용자는 혼란스러워할 수 있습니다. 출시 노트는 변경된 내용과 이유를 사용자가 이해할 수 있는 언어로 설명하기 위한 것입니다.
항상 현재 시제와 'Bazel now supports Y' 또는 'X now does Z' 형식을 사용합니다. 출시 노트가 버그 항목처럼 들리지 않도록 합니다. 모든 출시 노트 항목은 유익해야 하며 일관된 스타일과 언어를 사용해야 합니다.
지원 중단되거나 삭제된 항목이 있는 경우 'X has been deprecated' 또는 'X has been removed'를 사용합니다. 'is removed' 또는 'was removed'가 아닙니다.
Bazel이 이제 다른 작업을 수행하는 경우 현재 시제에서 'X now $newBehavior instead of $oldBehavior'를 사용합니다. 이렇게 하면 사용자가 새 출시를 사용할 때 예상되는 사항을 자세히 알 수 있습니다.
Bazel이 이제 무언가를 지원하거나 더 이상 지원하지 않는 경우 'Bazel now supports / no longer supports X'를 사용합니다.
무언가가 삭제 / 지원 중단 / 변경된 이유를 설명합니다. 한 문장으로 충분하지만 사용자가 빌드에 미치는 영향을 평가할 수 있도록 합니다.
향후 기능에 관해 약속하지 마세요. '이 플래그는 삭제됩니다' 또는 '이 플래그는 변경됩니다'를 사용하지 마세요. 불확실성이 발생합니다. 사용자가 가장 먼저 궁금해하는 것은 '언제?'이며, 사용자가 알 수 없는 시점에 현재 빌드가 중단될까 봐 걱정하지 않도록 합니다.
절차
출시 절차의 일환으로 모든 커밋의 RELNOTES 태그를 수집합니다. Google Docs에 모든 내용을 복사하여 노트를 검토, 수정, 정리합니다.
출시 관리자가 bazel-dev 메일링 리스트로 이메일을 보냅니다. Bazel 기여자는 문서에 기여하고 변경사항이 공지에 올바르게 반영되도록 초대됩니다.
나중에 Bazel 블로그에 공지가 제출됩니다. bazel-blog 저장소를 사용합니다.