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

CIの用途

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

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

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

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

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

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

ウェブブラウザーでPRを開く
下の方にCIの結果が表示されているので「Show all checks」をクリックする
「ci/circleci」の右側にある「Details」のリンクをクリックするとレポートページが開く。しかし、このプロジェクトの編集権限がない人には Artifacts（成果物）のタブが表示されない
そこで慌てず、URLの後ろに #artifacts を追加して、https://circleci.com/gh/rust-lang-ja/the-rust-programming-language-ja/03#artifacts のように開き直すと、成果物のリストが表示される
このリストで、例えば、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機能は、後日、追加する予定。

GitHubのリポジトリにpushするためには、User Keyの登録が必要。User KeyはGitHubアカウントに紐付けられ、writeアクセスを持つ。現在は、@tatsuya6502に紐付けたキーを使用している。

設定方法

CircleCIのプロジェクトページ https://circleci.com/gh/rust-lang-ja/the-rust-programming-language-ja を開く
Project Settingsリンクをクリックする
メニューから、Permissions → Checkout SSH Keysを選択する
（初回のみ）Add user keyのところにあるAuthorize w/GitHubボタンを押す。すると、GitHubのページに遷移し、自分のGitHubアカウントのPublic SSH KeysへのAdminアクセスを追加することについて、承認を求められる。Authorize applicationボタンを押して承認する。成功すると、CircleCIのページに戻る
Add user keyのところにあるCreate and add <ユーザー名> user keyボタンを押す。すると、ページ一番上のキーの一覧に、<ユーザー名> user keyが追加され、選択された状態になる。これで設定OK

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

良い点：

悪い点：