このドキュメントは、Bazel コントリビューターを対象としています。
Bazel の commit の説明には、RELNOTES:
タグとリリースノートが含まれます。これは、Bazel チームが各リリースの変更を追跡し、リリース通知を作成する際に使用します。
概要
変更内容はバグ修正ですか?その場合、リリースノートは必要ありません。GitHub の問題への参照を記載してください。
この変更により、ユーザーが認識できる方法で Bazel を追加 / 削除 / 変更する場合は、それについて言及したほうが良い場合があります。
大幅な変更の場合は、まず設計ドキュメント ポリシーに従ってください。
ガイドライン
リリースノートはユーザーが読むため、短くし(理想的には 1 文)、専門用語(Bazel 内部の用語)を避け、変更点に焦点を当ててください。
関連ドキュメントへのリンクを記載します。ほとんどのリリースノートに、リンクが記載されています。説明にフラグ、機能、コマンド名が記載されている場合、ユーザーはそれについてもっと知りたいと思うでしょう。
コード、記号、フラグ、アンダースコアを含む単語をバッククォートで囲みます。
バグの説明をコピーして貼り付けるだけではなく、多くの場合、難解で、私たちが理解するだけでは意味がなく、ユーザーが頭を傷つけたままになります。リリースノートの目的は、変更点とその理由を、ユーザーが理解できる言葉で説明することです。
常に現在形を使用し、「Bazel が Y をサポートするようになった」または「X が Z をサポートするようになりました」という形式を使用します。リリースノートがバグエントリのような印象を与えるのは避けたいと考えています。すべてのリリースノートのエントリは、有益で、一貫したスタイルと言語を使用する必要があります。
非推奨または削除が行われたものがある場合は、「X は非推奨になりました」または「X は削除されました」という表現を使用します。「削除済み」または「削除済み」ではありません。
Bazel の動作が変わった場合は、現在形で「$oldBehavior ではなく X now $newBehavior」を使用します。これにより、ユーザーは新しいリリースを使用する場合に何を期待できるのかを詳しく知ることができます。
Bazel でサポートされるようになりましたか、サポートされなくなった場合は、「Bazel が X をサポートするようになった、またはサポートしなくなった」を使用してください。
削除、サポート終了、変更の理由を説明します。1 文で十分ですが、ビルドへの影響をユーザーが評価できるようにする必要があります。
今後の機能について確約しないでください。「このフラグは削除されます」や「これは変更される」ことは避けてください。不確実性が生まれます。ユーザーが真っ先に疑問に思うのは「いつか」という疑問です。そのため、いつか不明な時点で現在のビルドが機能しなくなることを気にしなくて済むようにする必要があります。
プロセス
リリース プロセスの一環として、すべての commit の RELNOTES
タグを収集します。Google ドキュメントのすべてをコピーして、メモを確認、編集、整理します。
リリース マネージャーが bazel-dev メーリング リストにメールを送信します。Bazel コントリビューターは、ドキュメントへの投稿に招待され、変更内容がお知らせに正しく反映されるようにします。
その後、bazel-blog リポジトリを使用して Bazel ブログにお知らせが送信されます。