Policy:General (ja)

Jubatus の一般的な開発方針を定める。

1. 開発サイクル

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

毎月のイテレーション
- 年間リリース計画の確認 (必要であれば見直し)
- 次回リリースの計画立案
  - 年間リリース計画に基づく [Issue の棚卸し (機能/改善/バグフィックスなど、次のバージョンに取り込む Issue の選択)](./Policy:Issue-(ja)#-issue-)
  - リリース予定日とバージョン番号の決定
  - 次のバージョンの開発に使用する依存ライブラリのバージョンアップの調査/検討
- 開発作業の実施
- リリース直前の打合せで、リリースの必要なリポジトリの洗い出しと、コードフリーズからリリースまでの作業分担の決定
- リリース予定日の 2 日前 (12:00 JST) にコードフリーズを宣言
- リリース準備作業の実施
  - 致命的な不具合を除き、新規 Issue の割当ては行わない
  - リリースするバージョン番号を最終確定する
  - QA を行う (観点は後述)
  - ドキュメントの反映漏れ確認
- リリース作業の実施
- イテレーションの振り返り
  - 計画していたがリリースに含めることができなかった Issue について原因分析を行い、再発防止策を検討する
  - 作業の過程で発生/発見したプロセスの問題点などを共有し、再発防止策を検討する (レビュー観点に追加する、ポリシーを見直すなど)
- 最初に戻る

2. リリース方針

リリースに関わる最終判断はコミュニティでの合議で行う。

リリースサイクル

新機能や性能改善、バグフィックス等をタイムリーに提供するため、原則として、1ヶ月サイクル(1回/月)のリリースを行う。
- 大規模な変更を計画する場合は、リリース間隔を変更する場合もある。

バージョン付け

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

メジャー番号は、当面 0 とする。
マイナー番号は、大きな機能性の追加や一般ユーザに影響する互換性の破壊(コミュニティでの合議で判断)を含むリリースでインクリメントする。
リビジョン番号は、マイナー番号のインクリメントしないリリースでインクリメントする。

互換性の維持方針

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

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

方針:

できる限り同一マイナー番号の間は下位互換性を維持する。ただし、コミュニティの合議により、リビジョン番号のインクリメントで互換性が破壊されてもよい。
- 互換性を破壊する変更については毎回のリリースノートでドキュメント化し、ユーザに告知する。特に影響が大きいと思われる変更の場合はマイグレーション手段を用意する (コンバートツールなど)。

ブランチの運用方針 (全リポジトリ共通)

運用するブランチは以下の3種類である。

master

バージョン X.Y.Z としてリリース済みのコード

develop

バージョン X.Y.(Z+1) 版の開発中のコード
Pull-Request によるレビューが完了したコードのみがマージされる

作業用ブランチ (任意)

開発作業中のコード

備考

コードの変更(Pull-Request)は、作業用ブランチから develop ブランチへ送る。
リポジトリ間(例: Jubatus 本体, Jubatus Core, クライアント, サンプルなど)の互換性保証
- 同一名称のブランチ間でのみ互換性を保証する。(例えば Jubatus Core の master ブランチは Jubatus の develop ブランチで動作しない可能性がある)

リリース契機以外での 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 に貼る。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly