リリースノートの作成

問題を報告する ソースを表示

このドキュメントは、Bazel コントリビューターを対象としています。

Bazel の commit の説明には、RELNOTES: タグとリリースノートが含まれます。これは、Bazel チームが各リリースの変更を追跡し、リリースのお知らせを書き込む際に使用します。

概要

  • 変更はバグ修正ですか?その場合、リリースノートは必要ありません。GitHub の問題の参照を含めてください。

  • 可視的な方法で Bazel を追加、削除、変更する場合は、それについて言及することが有効な場合があります。

大幅な変更を行う場合は、まず設計ドキュメント ポリシーを遵守してください。

ガイドライン

リリースノートはユーザーによって読み取られるため、短く(できれば 1 文で)、専門用語(Bazel 内部用語)を避け、変更内容を重視する必要があります。

  • 関連ドキュメントへのリンクを記載します。ほぼすべてのリリースノートにリンクが含まれています。説明にフラグ、機能、コマンド名が含まれていれば、ユーザーは詳しい情報を知りたいでしょう。

  • コード、記号、フラグ、またはアンダースコアを含む単語は、引用符で囲みます。

  • バグの説明をコピーして貼り付けるだけではありません。これらはわかりにくいもので、Google にとって意味があり、ユーザーの頭を傷つけることになりかねません。リリースノートでは、変更点とユーザーが理解できる言語で説明されています。

  • 常に現在時制を使用し、「Bazel が Y をサポートするようになりました」または「X で Z がサポートされるようになりました」という形式を使用します。リリースノートがバグエントリのように聞こえないようにする必要があります。リリースノートのすべてのエントリは、有益な情報であり、一貫したスタイルと言語を使用する必要があります。

  • サポートが終了しているか削除されている場合は、「X のサポートが終了しました」または「X を削除しました」を使用します。「削除済み」または「削除済み」でない。

  • Bazel が別の動作をしている場合は、現在形の $oldBehavior ではなく X を使用します。これにより、ユーザーは新しいリリースを使用した場合に想定される動作を詳細に把握できます。

  • Bazel が現在サポート中またはサポートを終了している場合は、「Bazel が X をサポートするようになりました / サポートされなくなりました」を使用します。

  • 削除 / 非推奨 / 変更された理由を説明する。1 文で十分ですが、Google では、ユーザーがビルドに与える影響を評価できるようにしたいと考えています。

  • 今後の機能について、一切確約しないでください。「このフラグは削除されます」または「今後変更されます」は避けてください。不確実性が生じます。ユーザーが最初に疑問に思うのは「いつなのか」です。現在のビルドが不明な時間に機能しなくなることを心配しないためです。

プロセス

リリース プロセスの一環として、すべての commit の RELNOTES タグを収集します。メモは Google ドキュメントにコピーされ、確認、編集、整理されます。

リリース マネージャーが bazel-dev メーリング リストにメールを送信します。 Bazel コントリビューターはドキュメントに投稿するよう促され、その変更がお知らせに正しく反映されていることを確認します。

その後、bazel-blog リポジトリを使用して Bazel ブログにお知らせが送信されます。