Issue ハンドリングポリシーの見直し (2013/07/08)

_.md

差分: https://gist.github.com/kmaehashi/5947673/revisions

変更内容は以下の通り。

• 「ラベル」はissue作成時に設定し、「マイルストン」と「担当者」は打合せで設定することを明文化した。（これまで不明確だったため）

• 「「領域」ラベルは、原則として最適なものを 1 つだけ選ぶ」を追記　（「ラベル」の選択基準が人によって異なる問題への対応）

• 領域に対応するラベルとして「command」を追加。（otherラベルが肥大化することを防ぐため）

• マイルストーンの選択方針を以下のように改善　（以下は、実情に合わせて変更）

  • 「互換性を破壊する変更については、原則として直近のマイナーアップデート (0.X.Y の X がインクリメントされるタイミング) を選択する」を追加。
  • Near Future の意味を「直近の 3 ヶ月程度を目途に対応」に変更。
  • 「Pending」の運用フローが煩雑であったため、見直し。

• 「Issue のクローズ」ポリシーを追加。

  • マイルストーンが適切に設定されていることを確認することで、リリースノートの作成時間が短縮できる。
  • ドキュメントが書かれずに放置されている、他リポジトリへの波及影響が未対処であることがリリース直前に発見された、などの反省から、issue のクローズ時に確認することとした。

• その他、表現の修正や表記の統一を行った。

issue_policy.md

Issue の取扱いについて定める。

Issue のハンドリングポリシー

原則

• 過去の議論や経緯を追跡できるようにするため、全てのコミット (機能追加/改善/バグ修正) は原則として Issue に紐付かせる。
• ただし、作業効率を考慮して、以下の場合は Issue を作成しなくてもよい。
  • 通常の利用者に大きなインパクトがない変更
    • コーディングスタイルの修正
    • テストコードの追加/修正
    • 不要なファイルの除去
    • ビルドスクリプト等の修正
    • 小規模なリファクタリング
    • ログメッセージの追加/削除
  • master 以外のブランチ内で閉じた (未リリースの) バグを修正する場合
• コミットログには、 #NNN の形式で Issue ID を含める。ただし、master/develop 以外のブランチで開発している機能追加については、master/develop へのマージコミットに対してのみ含めればよい。

Issue の登録

作業の効率化 (各バージョンで取り組むべき Issue の選定やリリースノートの作成等) と責任の明確化のため、以下の方針で Issue を登録する。

• 登録時点では、以下のルールに従って「説明文」と「ラベル」を設定する。

  • コミッタ以外 (外部のコントリビュータ) が投稿した Issue のラベルは、コミッタが設定する。

• 「マイルストーン」と「担当者アサイン」は、毎週の打合せの場で、以下のルールに従って設定/変更する。

  • ただし、自明なものについては適宜設定/変更してよい。
  • 次回の打合せを待たずに決定する必要があるものは、チャット等でコンセンサスを得れば設定/変更してよい。

説明文

Issue の登録者は、説明文として以下の内容を記述する。

• [破壊される互換性](./Policy:General (ja)) (該当する場合)

  • 他リポジトリへの波及影響がある場合は明記する。

• バグに関しては、開発者が事象を再現するのに十分な情報。

• バグ以外の項目については、「なぜその機能/改善/リファクタリング等が必要だと思うのか?」「誰が嬉しいのか?」を意識して記述する。

  • 「自分が欲しいから」「その方が Cool だから」でもよい (重要度を判断する基準になればよい)

ラベル

各 Issue について、 「種類」(赤色) と 「領域」(青色) の 2 ラベルを必ず設定する。

• 「種類」ラベルは常に 1 つだけ選ぶ。
• 「領域」ラベルは、原則として最適なものを 1 つだけ選ぶ (止むを得ない場合は複数選んでもよい)。

種類	説明
feature	現在提供されている機能とは別の機能 (または機能のバリエーション) を追加
improvement	現在提供されている機能の制約条件を取り除くなどの拡張、または非機能性の向上
bug	約束されている機能が提供できていない状態を修正する
refactoring	モジュール構成の変更 (機能変更を伴わない)
test	試験を追加または修正する (機能変更を伴わない)
discussion	大きな課題を着手可能な課題レベルに落とすための検討議論を行うための Issue

          |(アーキテクチャレベルで検討が必要な問題は、feature/bug/refactoring ではなく discussion を選択する)

support |利用者からの質問等

領域	説明
algorithm	機械学習アルゴリズム
core	core 内のモジュール (algorithm 以外)
server	server 内のモジュール
client	クライアント
jenerator	コード生成器または生成されたコード
packaging	配布
plugin	プラグイン
command	コマンド
other	上記以外 (ビルドスクリプト等)

マイルストーン

• 取り組むべきバージョンが明らかな場合は、そのバージョンを選択する。

• 互換性を破壊する変更については、原則として直近のマイナーアップデート (0.X.Y の X がインクリメントされるタイミング) を選択する。

• 直近の 3 ヶ月程度を目途に対応したい Issue は、"Near Future" を選択する。

• 上記以降、もしくは対応するかどうか未定の Issue は、"Far Future" を選択する。

• 他の Issue が解決するまで取り組むことのできない Issue には、マイルストン「Pending」を設定する。

  • Pending となっている Issue は毎週の棚卸のタイミングで確認する

担当者アサイン

[各領域の担当者](List of Reviewers)、副担当者、または自分を選択する。

Issue のクローズ

Issue のクローズ時には、以下を行う。

• マイルストーンが適切に設定されていることを確認する。
• 他リポジトリへ波及する変更が対応済みであることを確認する。 (観点は以下に示す)
  • 対応済みでない場合は、対応を行うか、 対応するための Issue をそのリポジトリに作成する。

波及確認の観点

• ユーザインタフェース (API/コマンド/設定ファイル等) の追加/変更/削除

  • website: ドキュメントが書かれている/追従していること
  • jubatus-example: サンプルが追従していること
  • jubatus-tutorial-{python,ruby,java}: サンプルが追従していること
  • jubatus-{python,ruby,cpp,java}-skelton: サンプルが追従していること
  • jubatus-{python,ruby,java}-client: API のテストが追従していること

• ディレクトリ構成やファイル名の変更

  • jubatus: パッケージングツール(RPM)に反映されていること
  • website: リポジトリ内のファイルへのリンクが切れていないこと

• jenerator の変更

  • jubatus: wscript 内の引数が適切に修正されていること (./waf generate generate_client)
  • jubatus-*-client: generate.sh が動作すること
  • jubatus-service-skelton: 再生成されたものがコミットされていること

• プラグイン/datum のインタフェース変更

  • jubatus-service-skelton: 追従していること
  • jubatus-plugin-skelton: 追従していること

定期的な Issue の棚卸し

定例打合せ (週サイクル)

• 打合せ開始前に実施すること

  • 議論が必要な Issue はアジェンダに追記しておく (単なる報告であれば書かなくてよい/打合せ中の場で簡潔に報告する)

• 打合せで実施すること

  • 打合せの前日までの Issue の差分 (新規または内容が更新された Issue) について、レビューを行う。
    • Open Issues の先週からの差分を一覧表示 (Recently Updated でソート) して、(1件10秒くらいで)スピーディに確認する。
      • 担当者/ラベル/マイルストーンが設定されていない Issue については、その場で設定する
    • Close Issues の先週からの差分を一覧表示 (Recently Updated でソート) して、原因分析と対策の立案を行う。
      • テストを足す、レビュー観点を足す、仕様や I/F を変えてケアレスミスが発生しないようにする、など
  • マイルストーンが "pending" の Issue を一覧表示して、blocker となっている Issue が解決していないかどうかを確認する。

リリース直後の定例打合せ (月サイクル)

次のバージョンに取り込む Issue の選択を、以下の方針で行う。

打合せの前に以下のプロセスを各自で実施して、意見を固めておく。打合せは意思決定の場とする。

• 種類が bug の Issue は、原則直近のリリースで対処する。 (当該機能が deprecated である場合などを除く)
• マイルストーンが "far future" のものを一覧して、"naer future" に移動すべきものを選択する。
• マイルストーンが "near future" のものを一覧して、取り組みむものを選択する。 (以前から放置されているものを優先的に検討する:　Least Recently Updated でソート)

選択の方針:

• よりニーズの高いと思われる Issue を選択する
• やるべきことが多すぎるのであれば、工数を見積もって比較する

LGTM

LGTM 👍

LGTM