CI

[KeenS]

中の人がgenerateを忘れてたらHTMLドキュメントに反映されない素敵仕様になってる

TODO

• rustbook の入手方法を調べる(現状よくわからないけどソースをコンパイルするとたまに使えるようになる)
• travis ci CircleCI をセットアップする
  • On PR でCI
  • On master mergeでCI
  • On master merge CIが通ったらgh-pagesブランチに自動push
    • そのためのmakeターゲットを用意

[tatsuya6502]

@KeenS CI 環境ですが、来週少し時間ができそうなので、私の方で構築してみようと思います。まずは fork した方の個人レポジトリで試してみます。

いまのところの構想：

• Travis CI ではなく、Wercker を使う。Wercker はまだ使ったことがないのだが、以下のような利点があるようだ：
  • ビルド環境として、自分で作った Docker イメージが使える。rustbook 入りの Docker イメージを用意しておけば簡単
  • デプロイのサポートがしっかりしている。GitHub Pages へ push するときの credentials の管理が容易。（Travis CI だと暗号化したデータの扱いがイマイチで、merge 後のデプロイはいいが、PR 時では、暗号データの復号化ができないようなので、デプロイできない）
• PR 時の CI でも、生成した HTML を GitHub Pages へ push したい。といっても、ブランチは gh-pages の１つしか持てないので、pr/PR番号/ みたいなサブディレクトリを掘って、そちらにデプロイするか？（考え中）

[KeenS]

ありがとうございます。

PRでのHTML生成欲しいですね。Circle CIとかのように成果物を保存する機構があればそれで十分なのですがwerckerにはなさそうですね。私の方でも考えてみます。rustbookのバイナリを作ってcircle ci使うとかの手もあるかもしれないので。

[tatsuya6502]

そうですね。wercker では成果物を保存することはできないようです。もし Circle CI でなにかできそうでしたら教えてください。（私は今まで Jerkins CI や Travis CI でテストを動かすくらいのことくらいしかやってこなかったので、Circle CI も wercker も未経験なのです）

あと、詳しくは Issue #9 （rustbook のインストール方法を調べる）の方に書きますが、

まず、rustbook の入った Docker イメージを作ってみました。

それから、rustbook のバイナリは、pure Rust なくせに rustc に付随するライブラリに依存いていて、単体では動かないことがわかりました。musl libc によるスタティックリンクも rustbook では使えません。もし Circle CI で動かすなら、CI のステップの中で Rust nightly のインストールと rustbook のビルドの両方を行ったほうがいいかもしれません。

[tatsuya6502]

遅くなりましたが、本件、ようやく着手しました。

PRでのHTML生成欲しいですね。Circle CIとかのように成果物を保存する機構があればそれで十分なのですがwerckerにはなさそうですね。

そうですね。wercker では成果物を保存することはできないようです。

一応、wercker にも、成果物を保存する機能はありました。そこで、試しに自分のリポジトリで、PR がオープン/更新された時に、wercker で HTML が生成されるようにしてみました。

• PR #2 tatsuya6502/the-rust-programming-language-ja

成果物（HTML）の取得のしかた

1. ウェブブラウザーで、上記ページを開く
2. 「All checks have passed」の所にある「Show all checks」をクリックすると、「wercker/build — Wercker pipeline passed」と表示される
3. 「Details」のリンクをクリックすると、このページ が開く
4. 「save artifacts [Download]」をクリックすると、「Download artifact」という水色のボタンが表示されるので、それをクリックする。output.tar というファイルがダウンロードされる（このファイル名は変えられないようです）
5. ターミナルから tar xf output.tar を実行して tarball を展開すると、artifacts というフォルダが現れる
6. artifacts の中にある、public-1.9.txz、または、public-1.6.txz を tar xf public-1.9.txz などとして展開する。（それぞれ、public/1.9/ と public/1.6/ に展開される）
7. HTMLファイルをウェブブラウザーで開く

まずは、この PR での HTML 生成の機能だけ使い始めたいと思います。設定ファイルや手順書などを整理してから、PR を上げますね。gh-pages への自動 push は、もう少し慣れてきたらやってみます。（また、比較のために、CircleCI も試してみたいと思っています）

それから、もう一点。PR の時に、HTML をダウンロードしないでレビューする方法も試しています。まずは無料でできそうな、Heroku の新サービス「Review Apps」を試そうとしています。

いまは、その前段階として、静的な HTML を Heroku からサーブする実験をしています。実は、Heroku は今日初めて使ったのですが、とりあえずは、nickel.rs によるウェブサーバーで、HTML 生成済みの Rust 日本語ドキュメントを表示できるようにはなりました。（nickel.rs も初めて触りましたが、この程度の内容なら簡単にできますね）

• http://review-rust-lang-ja.herokuapp.com/

リポジトリ内の構成は、当リポジトリとは違うのですが、こちらのテスト用のリポジトリからデプロイしています。

• https://github.com/tatsuya6502/hello-heroku-rust-nickel

この後、Review Apps の実験をして、もし良さげなら、当リポジトリが Heroku にデプロイできるようにするために、Heroku の build pack というものをカスタマイズします。

[tatsuya6502]

（また、比較のために、CircleCI も試してみたいと思っています）

CircliCI も試し始めました。とりあえず、Rust や rustbook のインストールなどは後回しで、あらかじめ生成済みの HTML を、成果物として保存するところだけ試してます。成果物が output.tar という１つのファイルに固められてしまう wercker とは異なり、ウェブブラウザーから、個別のファイルを開けるので、ファイルをダウンロードせずにレビューできて便利ですね！

Artifacts タブの内容 https://circleci.com/gh/tatsuya6502/the-rust-programming-language-ja/3#artifacts

$CIRCLE_ARTIFACTS/
    1.6/
        book/            <= TRPL
        favicon.inc
        footer.inc
        full-toc.inc
        index.html       <= ドキュメントホーム
        jquery.js
        main.css
        main.js
        playpen.js
        rust.css
        rustdoc.css
        search-index.js
    public-1.6.txz       <= public/1.6 全体をアーカイブしたもの

（標準ライブラリのドキュメントなどは、非圧縮だとサイズが大きいので、$CIRCLE_ARTIFACTS/1.6 には置かず、public-1.6.txz だけに含めるようにしてます）

CircleCI のアカウントがない人や、プロジェクトへのアクセス権がない人には、Artifacts のタブが表示さないようになっているみたいですが、上の URL （...#artifacts）を指定すると、（タブは無くても）成果物が表示されますね。これは、私にとっては都合がいいのですが、正しい動作なのか（アクセスできていいのか）微妙です。ま、public なプロジェクトなのだから、いいのかな。

rustbook のインストールや、PR を受けた時の動作も試してみますね。

[tatsuya6502]

CircleCI で Rust と rustbook のインストールができるようになったので、PR での HTML 生成について試してみました。

やはり、成果物（生成された HTML）がブラウザーで直接開いて見られるところが、wercker より使いやすいです。また rustc や rustbook がキャッシュされるようにしたところ、ビルド時間も４分弱と、十分短く抑えられました。（wercker だと１分半程度）

レビュー時の使いやすさを優先して、本プロジェクトでは、CircleCI を使おうと思います。CircleCI を使えるようにするための PR を、今夜か明日、オープンしますね。

以下、PR のテストについてです。

• PR #3 tatsuya6502/the-rust-programming-language-ja

成果物（HTML）の閲覧のしかた

1. ウェブブラウザーで、上記ページを開く
2. 「Some checks were not successful」の所にある「Show all checks」をクリックすると、「 ci/circleci — Your tests passed on CircleCI!」と表示される。（なお、wercker の方が fail しているのは、このブランチに、wercker の設定ファイルが無いため。無視してよい）
3. 「Details」のリンクをクリックするとレポートページが開く。しかし、このプロジェクトの編集権限がない人には Artifacts（成果物）のタブが表示されない。
4. URL の後ろに #artifacts を追加して、https://circleci.com/gh/tatsuya6502/the-rust-programming-language-ja/22#artifacts で開き直すと、成果物のリストが表示される。
5. 例えば、1.9/book/getting-started.html を
   クリックすると、生成された HTML を見ることができる。

[tatsuya6502]

レビュー時の使いやすさを優先して、本プロジェクトでは、CircleCI を使おうと思います。CircleCI を使えるようにするための PR を、今夜か明日、オープンしますね。

PR をオープンしました　→　#149

よろしくお願いします。

[tatsuya6502]

gh-pages ブランチへの自動 push も実装して、PR をオープンしました　→　#151

[tatsuya6502]

PR #149 と #151 をマージして、当初予定していた機能を一通り実現できました。

• On PR でCI
• On master mergeでCI
• On master merge CIが通ったらgh-pagesブランチに自動push

一番最近の CI レポートはこちらです：https://circleci.com/gh/rust-lang-ja/the-rust-programming-language-ja/4

本 issue は対応完了ということで、クローズします。

[KeenS]

🙏 👏