B-Wiki - OpenLaszloのcontributorになるには/Code_Review_Process

wiki top / OpenLaszloのcontributorになるには / Code_Review_Process

コードレビュープロセス †

このドキュメントは、ソース・データベースにコミット権限を持つ各々の開発者が使う変更プロセスを説明するものです。そのうちcontribution process(原文)を使う方法と統合したいと望んでいます。現時点では、プロセスを明らかにするためと、統合への第一ステップとしてここに公開します。

↑

概要 †

コードレビューはコードを開発ツリーに入れるための承認のプロセスです。私たちは開発ツリーに不具合が混入することを避けるためにコードレビューを行います。また、ニーズにマッチした製品を作ることを確実にするためでもあります。

コードレビュープロセスのゴールは、不具合が他の人に迷惑を掛ける前に、あるいは膨大なコードに紛れて見つけられなくなってしまう前に捕まえることで、時間を節約することです。不具合とは、機能的な問題(バグ)、脆弱だったり理解しづらかったりするコードの保守の問題、不必要な機能や要求(requirement)にマッチしない機能によってトレーサビリティが低下する問題のことを言います。

このドキュメントのゴールは、私たちが実際に用いている開発ツリー変更のプロセスを説明することと、そのプロセスを首尾一貫したものにすることです。これは出発点であって、目的地ではありません。チームが経験を得て成長して行くにつれて、ソフトウェアの部品のように、私たちはこれをデバッグし、最適化していきます。このプロセスは私たちがかつて行ってうまくいった方法の派生形です。一般的な作業の原則として知られています。

↑

役割 †

↑

Author †

Authorはレビュー中のプロダクトを作った人です。Authorはレビュー・セッションに先立って、必要なものを提供します。わかりやすく言い換えたり、概要説明を使って論理的にReviewerをリードします。また、機能、目的、レビュー中に提出されたものの関係などについての質問に答えなくてはなりません。Authorの究極的な責任は、レビュー中に発見された問題を修正することです。

↑

Reviewer †

Reviewerの仕事は、作成されたものに含まれる問題点を発見することです。ReviewerはAuthorによって提供されたものと、既に存在する他のものとの関係を吟味します。実装の問題点という観点と、実装がベースにしている設計という観点の両方で見なくてはなりません。設計によって提供された仕様と実装がマッチしなければ問題となります。レビューに関する領域に詳しく、コミット権限があるメンバであればコミュニティの誰でもReviewerになれます。

↑

プロセス †

↑

Request(Author) †

AuthorはReviewerにレビューしてもらうためのセットをパッケージングします。

SubmitAChangeForReview(原文)に説明されている「svn変更パッケージングツール」を良く理解します。
コード・ガイドライン(原文)(翻訳)に則っているかどうかを確かめます。Code Review Checklist(原文)をチェックしましょう。
あなたの変更に対するテストケースを書きます。新しい機能を実装するのであれば、その機能が正しく動作することをテストケースで保証してください(境界条件、エラー報告、および全てのコード分岐を網羅していることが望ましいです)。不具合を修正する場合、そのテストケースは修正していないコードの不具合を明らかにするようなものになります。あなたのテストケースをビルドファイルに追加してください。
ドキュメンテーションを変更後の機能性にマッチするよう更新します。新しい機能にはドキュメンテーションを追加してください。追加/変更したドキュメントは変更リストの一部となります。
あなたの変更の説明を書きます。これは、コード変更の概要、実装した機能あるいはタスクの名前、および障害報告の番号を含みます。このテンプレートを利用するか、bashスクリプトsvn-makechangepackageを利用してください。svn-bash.shはここ(svn)から利用できます。
最新ソースと同期し、smoke testをパスするか確かめます。
Reviewerにsvn-makechangepackage(以下を参照)とbashスクリプトsvn-review(これもsvn-bash.shから利用できます)で作成したレビューパッケージをメールします。laszlo-dev MLにCCしていることを確かめましょう。
Reviewerはあなたの変更パッケージを見るか、あなたのコンピュータの前に座って(もし可能ならば)あなたのコードをレビューします。後者の場合、Reviewerがマウスをコントロールできることが重要です。画面を操作できない場合、Reviewerはたくさんの再帰テストを見逃します。(訳注:「regressions」を「再帰テスト」としましたが、デグレを見逃すと言いたいのかも知れません)
変更がバグ修正の場合、バグはレビューステータスになり、Reviewerがアサインされます。

レビューパッケージを作成するには、svn-makechangepackageを利用することができます。

svnツリー上でファイルを変更します。
リリースノートを変更セットの説明に入れます。
svn-makechangepackageというシェルコマンドを実行します。すると、patch...から始まるファイルができます。
patchファイルをレビュアーに送ります。laszlo-dev MLにCCしてください。

↑

Review (Reviewer) †

Reviewerは変更を吟味します。

変更の説明を読みます。タスクが現在のマイルストーンに対して適切かどうかを確認します。また、それぞれのタスクが実装する機能の説明、あるいは変更セットが修正する不具合の説明を理解します。
svn diff(あるいは都合のよいフロントエンド)を用いて変更を吟味します。ファイルの変更や新しいファイルがコードガイドラインに則っているか確認します。全ての変更がリリースノートに説明されているか確認します。全ての変更や追加のファイルを理解できるか確認するとともに、機能がどのように実装されているかを理解します。設計書がある場合、コードと設計書をチェックします。また、設計の変更の場合は仕様に則っているかチェックします。仕様変更の場合、要求(requirement)に則っているかをチェックします。
テストケースが、失敗しそうなあるいは失敗するべきケースをカバーしているかを確認します。
不具合や、不足しているテストケースがあればまとめ、Authorに送ります(これはたとえ一緒にコーディングしているとしてもメールで行われるべきです)。修正しなければならないももののリストと、修正した方がいいもののリストに分類します。

Note: A confusing though correct piece of code can be in either category, depending on how likely it is to cause subsequent maintenance problems.
(訳注:↑係り受けが良くわかんない。どう訳すべき？categoryってなにを指している？)

Reviewerはコンパイルを試してみる必要はありませんし、テストケースが動作するか確認する必要もありません。Reviewerの仕事は自動的に検出できない問題を見つけることです。

↑

Response (Author) †

「修正しなければならない」問題を修正します(混乱したり、明確でないコードはしばしばリファクタリングしたり、ドキュメントを追加したり、設計ドキュメントを追加することで修正されます)。
残されたままになっている不具合をソースコードのコメントや設計ドキュメント、ややこしい課題として明記します。
変更の説明を更新します。
コードが変更されたり、それなりの量のドキュメントが更新された場合、Requestのところからやり直します。そうでなければSubmitに進みます。

↑