CI 継続的インテグレーション

CIの用途

本リポジトリでは、CI（継続的なインテグレーション）を、以下の用途に使用している。

• PR（プルリクエスト）でCIを実行し、レビュー用のHTMLを自動生成
  • PRがオープンされた時と、その後、PR元のブランチに追加コミットがあった時に、都度、実行される
• （現時点で未実装）masterにマージされた際にCIを実行し、CIが通ったらHTMLをgh-pagesブランチへ自動push

なお、マークアップなどに問題があっても、（2016年6月現在では）rustbookは警告やエラーを出してくれないので、品質の確認には使えない。

CircleCIを利用

CircleCIの無料プランを利用している。

2016年6月時点の無料プランの内容

• 上限：ビルド時間の上限は1,500分/月
  • 本リポジトリでは１回の実行は３から５分程度なので、月間300回くらいはビルド可能と思われる
  • 上限に達した場合でも、gh-pagesへpushするHTMLの生成などをローカルのMac/PCで行えばよいので、それほど不便ではない
• １コンテナ
• 多重実行は最大４ジョブまで可能
  • 現在の設定値はデフォルトの１ジョブのまま（特に変える必要もないため）

プロジェクトページ

　https://circleci.com/gh/rust-lang-ja/the-rust-programming-language-ja

生成されたHTMLの閲覧や、ダウンロードの方法

1. ウェブブラウザーでPRを開く
2. 下の方にCIの結果が表示されているので「Show all checks」をクリックする
3. 「ci/circleci」の右側にある「Details」のリンクをクリックするとレポートページが開く。しかし、このプロジェクトの編集権限がない人には Artifacts（成果物）のタブが表示されない
4. そこで慌てず、URLの後ろに #artifacts を追加して、https://circleci.com/gh/rust-lang-ja/the-rust-programming-language-ja/03#artifacts のように開き直すと、成果物のリストが表示される
5. このリストで、例えば、1.9/book/getting-started.html を クリックすると、生成された HTML を見ることができる。

なお、標準ライブラリのドキュメントなどは、非圧縮だとサイズが大きいため、圧縮ファイル（例：public-1.9.txz）だけに含めるようにしている。

設定ファイルなど

CIの設定は、circle.yml に書かれている。また、tools/circleci/setup-rust.sh も使用している。

全体の流れ

• 環境変数を設定する。その中には以下のようなものがある。
  • RUST_NIGHTLY_RELEASE_DATE - rustbookがnightly版を使用するので、そのビルド日付（例："2016-06-01"）
  • RUSTBOOK_GIT_URL - rustbookソースコードのダウンロード元のgitリポジトリ（例：https://github.com/tatsuya6502/rustbook.git）
  • RUSTBOOK_GIT_BRANCH - 同リポジトリのブランチ（例：rust-1.11.0-nightly）
• 依存ツールやライブラリをセットアップする
  • curl, gcc, git, make といったツール類。毎回、インストール
  • Rust nightly版、cargo、rustbook。これらはみな、CircleCIにキャッシュされるので、同じバージョンを使い続ける間は、インストール時間を節約できる
• HTMLの生成
• 成果物（HTML）の保存

gh-pagesへの自動push機能は、後日、追加する予定。

他のCIサービスなど

wercker

2016年6月時点で wercker も試用したが、不便な点があり、採用を見送った（詳細）

良い点：

• 指定したDockerイメージ上でCIを実行できるので、環境の制御がしやすい
• 無料プランで、事実上、無制限に使える、など

悪い点：

• 成果物（生成されたHTML）の閲覧が不便。オンラインでの閲覧ができず、tarballをローカルにダウンロードする必要がある

Travis CI

Travis CI

• gh-pagesへの自動pushに使うGitHubトークンといった、センシティブな情報の管理が不便