kmaehashi/_.md

## _.md

      
    Raw
  

              _.md
            
          
    差分: https://gist.github.com/kmaehashi/5947889/revisions
変更点は以下。


「リリース直前の打合せで、リリースの必要なリポジトリの洗い出しと、コードフリーズからリリースまでの作業分担の決定」を追加　（作業を明確にすることでリリース直前に慌てないようにする）


「リリース契機以外での master ブランチの変更」を追加　（masterブランチを変更してよい例外ケースの明文化）


## general_policy.md

      
    Raw
  

              general_policy.md
            
          
    Jubatus の一般的な開発方針を定める。
1. 開発サイクル

Jubatus の開発は以下のイテレーションの繰り返しで進行する。

毎四半期のイテレーション

次期マイナーバージョンの計画立案

クローズドで開発している機能の取り込みマイルストーンを立案する

GitHub ブランチへの公開時期
性能/精度、優位性の評価に基づく、メインラインへのマージ可否の判断時期
rebase 作業完了時期
リリース時期
ドキュメント作成計画


[Issue の棚卸し (今四半期に取り組む Issue の選択)](./Policy:Issue-(ja)#-issue-)


毎月のイテレーション

次回リリースの計画立案

[Issue の棚卸し (機能/改善/バグフィックスなど、次のバージョンに取り込む Issue の選択)](./Policy:Issue-(ja)#-issue-)
リリース予定日とバージョン番号の決定
次のバージョンの開発に使用する依存ライブラリのバージョンアップの調査/検討


開発作業の実施
リリース直前の打合せで、リリースの必要なリポジトリの洗い出しと、コードフリーズからリリースまでの作業分担の決定
リリース予定日の 2 日前 (12:00 JST) にコードフリーズを宣言
リリース準備作業の実施

致命的な不具合を除き、新規 Issue の割当ては行わない
リリースするバージョン番号を最終確定する
QA を行う (観点は後述)
ドキュメントの反映漏れ確認


リリース作業の実施
イテレーションの振り返り

計画していたがリリースに含めることができなかった Issue について原因分析を行い、再発防止策を検討する
作業の過程で発生/発見したプロセスの問題点などを共有し、再発防止策を検討する (レビュー観点に追加する、ポリシーを見直すなど)


最初に戻る


2. リリース方針


リリースに関わる最終判断はリリースマネージャ (@suma) が行う。

リリースサイクル


原則として、1ヶ月に1回のリリースを行う。

大規模な変更を計画する場合は、リリース間隔を変更する場合もある。


ただし、検討経緯 (注1) を踏まえて、「Jubatus のアーキテクチャ/インタフェース/品質が十分にstableとなり、頻繁なリリースを行う必要性が低くなった」と判断されるタイミングで、「リリース方針」全体の見直しを行う。


バージョン付け

X.Y.Z (major.minor.revision) は以下の契機でインクリメントする。

メジャー番号は、当面 0 とする。
マイナー番号は、大きな機能性の追加を含むリリースでインクリメントする。

リリースマネージャの提案でインクリメントを検討し、コミュニティで議論する。


リビジョン番号は、マイナー番号のインクリメントしないリリースでインクリメントする。

リリース単位 (= バージョン付けの単位) は Jubatus リポジトリ全体とする (core/server モジュールについて別のバージョンを振ることも可能だが、現時点では行わない)。
関連リポジトリのバージョン付け


jubatus-msgpack-rpc, jubatus-mpio

上記のバージョン付けポリシに順じて独自にバージョンを付ける (Jubatus 本体のバージョンとは無関係とする)


クライアント

API の変更を伴う場合 (新エンジン追加、シグネチャ修正等)

Jubatus 本体のリリースのタイミングでリリースする。
バージョンは、Jubatus 本体の数値に合わせる。


API の変更を伴わない場合 (バグ修正等)

現在のバージョンに対してパッチレベル ("-p1" など) を付けてリリースする。


Example, チュートリアル, スケルトン, インストール用ツール

バージョン付けは行わない。
互換性を明示するため、Jubatus 本体のリリースのタイミングで、Jubatus 本体のバージョンを示すタグを打つ (ただし変更がない場合を除く)。


Web サイト

Example 等と同等に扱う。


互換性の維持方針

ここでの「互換性」は以下のインタフェースについての議論であり、内部 I/F は含まない。

サーバの設定ファイル
クライアント-サーバ間 (RPC)
save したモデルファイルのフォーマット
フレームワークと、その上で開発された機械学習エンジンの間の API

方針:

できる限り同一マイナー番号の間は下位互換性を維持する。ただし、リリースマネージャの判断で、リビジョン番号のインクリメントで互換性が破壊されてもよい。

互換性を破壊する変更については毎回のリリースノートでドキュメント化し、ユーザに告知する。特に影響が大きいと思われる変更の場合はマイグレーション手段を用意する (コンバートツールなど)。


リリース契機以外での master ブランチの変更

以下の場合は、リリースを待たずに、master ブランチに対して修正を行ってよい。
master に対して行った変更は、必ずその場で develop にマージする。設定済みのタグの打ち直しは行わない (検討経緯 (注2) を参照)。

Jubatus 本体

なし


jubatus-msgpack-rpc, jubatus-mpio

なし


クライアント

なし


Example, チュートリアル, スケルトン, インストール用ツール

上位互換性を破壊しないバグ修正や機能の追加


Web サイト

デッドリンクや単純な typo の修正
バージョンに依存しないコンテンツ (Publications など) の追加/修正


また、全てのリポジトリについて、主として Jubatus チーム内で利用するファイルの追加/修正 (パッケージングツール、Travis 設定ファイル、クライアントの generate.sh など、原則としてユーザに影響を与えない箇所) についての追加/修正は OK とする。
3. 依存ライブラリのバージョン選択基準


「必須バージョン」(Required)と「推奨バージョン」(Recommended)の 2 種類を設ける。


「必須バージョン」は、ライブラリの提供するAPIとJubatusが論理的に整合する最低限のマイナーバージョンを規定する (例えば、ZooKeeper 3.3 以降など)。

必須バージョンの変更は、バージョンアップによって得られる機能向上の度合いと、影響範囲 (各 Linux ディストリビューションの公式パッケージでの採用状況など) を総合的に勘案する。原則として Jubatus のマイナーバージョンアップのタイミングでのみ変更する。


「推奨バージョン」は、「必須バージョン」の範囲内のリビジョン (同一の API を提供するバージョン範囲) について、動作保証するバージョンを規定する。jubatus-installer、パッケージはこのバージョンで提供する。CI/開発者の環境も本バージョンを使用する (例えば、ZooKeeper 3.4.5 など)。

推奨バージョンは、影響のあるバグフィックスが含まれている場合は積極的に変更する。Jubatus の各リリースごとに見直しを行い、Wiki で公開する。


4. リリース QA 観点


単体テスト

自動テストが全ての configure バリエーションで通過すること (Jenkinsで実施)


結合テスト

各言語クライアントからの API ルート試験がすべて通過すること (Jenkinsで実施)


連続運転/分散環境テスト

分散環境で各プロセスを起動し、1日以上、ランダムなリクエストを発行し続けてダウンしないこと。 (自動化環境を用意する)
QPS/精度を測定し、前回のバージョンと大きく差がないこと (自動化環境を用意する)


5. ポリシーの変更

ポリシーの変更は、以下の手順によって行う。

提案者は、「変更後の内容」・「変更すべき理由」・「変更によって得られるメリット」を文書化して提示する。
全体打合せで変更の提案を行う。1 週間後までにメンバの過半数の LGTM が文書上のコメントとして得られていれば承認とする。

脚注

(注1) リリースサイクルの検討経緯


案

長めのリリースサイクル（数か月スパン or 大きな機能の完成を契機としたリリース）

メリット

中・長期的な視点で開発計画を立案できる
利用者に与える互換性に関する影響が少ない (同じインタフェースのソフトウェアをより長く使い続けることができる)


デメリット

bug-fix/改善などのユーザに対するデリバリが遅くなる


短めのリリースサイクル（1か月単位でのリリース）

メリット

コミュニティから迅速なフィードバックが得られる
リリースによる継続的なアピール効果 (コミュニティのプレゼンス)


デメリット

リリースコストが毎月かかる


議論

現在の Jubatus は、より最適な分散機械学習のためのインタフェースを探求する段階であり、過去との互換性を保証することに重点を置くとコスト高である。
また、機能追加/バグフィックスが非常に頻繁に行われているため、それらに対するユーザからのフィードバックを迅速に得られることのメリットの方が大きい。


(注2)

タグについては以下のような位置づけとする。

(今のところ)過去のバージョンはサポートしていないため、古いバージョンを利用したいユーザは関知しない。
ただし、最低限の簡便性を考慮して、「タグ V 以降のコミットは、Jubatus V-1 に対応していない(可能性がある)」ということは明示しておく。

Example, チュートリアル, スケルトン, インストール用ツール

どうしても V に対応する最新コミットが必要なユーザには、タグ V+1 の 1 個前のコミットを参照してもらう。


Web サイト
　　- リリースの度に、「V+1 の 1 個前のコミット」へのダウンロードリンクを Wiki に貼る。