開発者ノート (略して「dev note」) とは、Making WordPress Core ブログにおいて、次のリリースにおける技術的な変更と、その変更について開発者が知っておくべきことを詳細に説明するブログ記事のことです。
開発者ノートは、WordPress コアのリリースサイクルにおいて重要です。WordPress の構築方法に影響を与える可能性のある変更について開発者コミュニティに情報を提供し、問題点、解決策、ベストプラクティス、エッジケースを説明することでインラインドキュメントを補完します。
最高の開発者ノートとは、明確で、簡潔で、完全なものです。
開発者ノートが必要なものは、どのように判断しますか ?
各リリースにおいて、開発者ノートが必要なチケットは Trac 上で needs-dev-note
キーワードが与えられます。チケットにノートが投稿されると、そのキーワードは has-dev-note
キーワードに置き換えられ、コメントにノートへのリンクが含まれます。
重要なのは、Trac で needs-dev-note
とマークされたマイルストーンのすべてのチケットがコミットされ、そのリリースに含まれるわけではないということです。
そのため、チケットや変更点のノートを書くのは、その変更点がリリースに含まれることが明らかになってから行うべきです。通常、これは closed
ステータス (ときには reopened
ステータス) のチケットに焦点を当てるべきことを意味します。
誰が開発者ノートを書きますか ?
開発者ノートを作成する人の優先順位は、以下の通りです。
- その変更について、深く実用的な知識を持っている人。これは通常、それ変更したコミッター、その変更の作成とテストを手伝ったコンポーネントのメンテナー、またはその変更を前進させることを手伝ったその他の貢献者です。
- その変更に関わっていないが、技術的な基礎があり、正しいメッセージを伝えるためにコードの変更を詳細にレビューできる人。
- 技術的なことはあまり詳しくないが、ノートを書くうえで必要な情報を得るために、変更点について上記のグループの誰かにインタビューしたり質問したりできる人。
開発者ノートには何を書くべきですか ?
それぞれのノートはユニークなものですが、すべての開発者ノートは、解決されようとしている問題、その問題がどのように解決されたか、開発者が関連する変更について知っておくべきことなどを明確に定義する必要があります。通常、以下のような内容が混在しています。
- 問題を明確にする。
- なぜ問題なのかを説明する。
- 開発者は現在、理想的とは言えない方法で問題を解決しているのかどうか。
- この問題に対処するために、プラグインやテーマにおいてすでに確立されたパターンがあるのかどうか。
- 現在のプラクティスまたは使用方法、およびコードベースの現在の状態が、どのように問題の原因となりうるかをドキュメント化する。
- 理想的な行動とは何か、またその理由を記述する。
- 望ましい行動や結果を達成するために行った変更を説明する。
- 変更後の機能や特徴、API を正しく使用するための例を提供する (ベストプラクティスの確立)。
- 後方互換性に関する考慮事項を特定し、それらがコアでどのように対処されたか、またプラグインやテーマでどのように対処されるべきかを説明する。
- 判明しているエッジケースについての詳細。
- Trac や GitHub のチケット、チェンジセット、過去の開発者ノート、Make ブログの過去の投稿など、必要に応じて変更に関する追加資料へのリンクを貼る。
ときには、言及する価値はあるが、個々の開発者ノートを書くほど詳細ではない大きな変更点があります。複数の変更を一つの開発者ノートにまとめることは、むしろ良いことです。
コンポーネントのメンテナーが、そのコンポーネントについて、いくつかの異なる変更点を詳述した一つの開発者ノートを公開することはよくあることです。また、より一般的な「X.X での開発者向けのさまざまな変更点」という開発者ノートとして、言及すべき残りの小さな変更点をまとめて発表することもよくあります。
チケットを調査してから開発者ノートを書く前に、「これは長々とドキュメント化する必要がある変更なのか、一文を記載するだけで十分なのか、その変更に関連する技術的なものはないか」などを考慮すべきです。
目標は、記事の長さ、関連する変更とトピック、そしてリリース中に公開される開発者ノートの数のバランスを見つけることです。開発者ノートの数は、少ないより多いほうがよいでしょう。しかし、読者がノートに飽きて読むのをやめてしまわないように注意することが重要です。
開発者ノートはレビューされるべきですか ?
Making WordPress ブログのすべての記事は、少なくとも他の人によって査読されるべきです。開発者ノートの場合、「少なくとも」2人のレビュアーが必要です。
- 投稿の正確さを確認し、重要な点を見落としていないことを確認するための1回の技術的レビュー。
- 文法やスペルなどの誤りを発見するための1回のコピーレビュー。
少なくとも2件のレビューを受けたら、そのリリースのドキュメンテーションリードに連絡を取ってください。彼らは、計画中または進行中のすべての開発者ノートの概要を把握し、公開のタイミングを調整できます。「開発者ノート疲れ」を防ぐために、開発者ノートを分散させることが重要です。たとえば、3つ以上の開発者ノートを同じ日に公開するべきではありません。
開発者ノートをいつ公開すべきですか ?
開発者ノートは、リリースサイクル中いつでも公開できます。コードベースへの変更が今日コミットされれば、開発者ノートは明日公開されるかもしれません。しかし、通常は変更をコミットした後、テストのために数日待つことがベストでしょう。
WordPress の貢献者の中には、自分のサイトで trunk
を運用し、変更箇所をすべてテストしている人も少なくありません。ときには、調整が必要な問題が発生することもあります。開発者ノートの公開を待つことで、1つの変更に対して1つのノートしか必要ないことが保証され、混乱の可能性や開発者の仕事を増やすことを避けることができます。
ただし、特定のリリースでの変更に関するすべての開発者ノートは、そのリリースの最初のリリース候補の前に公開されるべきです。
次期リリースに関するドキュメントを整理するために、リリース候補版1と同時に、WordPress のメジャーバージョンごとにフィールドガイドが作成・投稿されます。
過去のリリースにおけるすべてのフィールドガイドは、こちらで確認できます。make.wordpress.org/core/tag/field-guide
その他のヒント
以下は、開発者用ノートを書くために役に立つ追加のリソースとヒントです。
トーンとスタイル
Making WordPress Core ブログで記事を書いたりレビューしたりするときには、投稿とコメントのガイドラインを覚えておくことが重要です。特に、スタイルと内容のセクションは重要です。このページのガイドラインは、WordPress のすべての公式チャンネルにおいて、一貫したトーンと表現によって明確なコミュニケーションを確保するために役立ちます。
タグ付けとカテゴライズ
開発者ノートを書いた後は、それが正しくタグ付けされていることを確認することも重要です。すべての開発者ノートには dev-notes
というタグと、特定のバージョンタグ (たとえば 5.5
) が必要です。必要に応じてタグを追加でき、通常、特定のコンポーネントに関するタグを含みます。
ノートに適切なタグを付けることは、後で見つけやすく、再度確認しやすくするために重要です。
特定のリリースの開発者ノート、ブログに書かれたすべての開発者ノート、あるいは特定のコンポーネントの開発者ノートがあります。
Attribution
開発者ノートを公開するときには、必ず一番下に「props」の行を入れるようにしてください。たとえば、「Props @janedoe による技術的なレビュー, @johndoe による校正」などです。
こうすることで、その投稿に貢献したすべての人が正しく評価され、読者は投稿の関係者を知ることができ、コメントや質問がある場合は誰に向けて発信しているのかが分かります。