Kengo's blog

Technical articles about original projects, JVM, Static Analysis and TypeScript.

Read The Docs利用者用にPRレビュー支援Probotを作りました

私がSpotBugsなどで使っているドキュメントホスティングサービス、Read The Docsを使う上で助けになるGitHub Probotを作成しました。

github.com

ドキュメントがいつもどおり全部英語なので、日本語での解説をここに書いておきます。

想定ユーザ

  • Read The Docsを使ったドキュメント作成を複数人で行っている
  • Read The Docsの設定をあまりいじっていない

解決する問題

  • Read The Docsが単体でPRレビュー用ビルドを提供していないので、レビューしてもらう時にステージングサイトやスクリーンショットを主導で用意しなければならない。

解決手法

  • PR作成時に docs ディレクトリに変更が入っていれば、Read The Docs上でのビルドとホスティングを有効化し、アクセス用URLをPRに書き込む。

インストール方法

  1. Read The DocsプロジェクトをGitHubリポジトリと接続しておく、あるいはGitHub Webhookと統合しておく
  2. Read The Docsプロジェクトに rtd-bot ユーザをメンテナーとして招待しておく。
  3. Gitリポジトリ.github/config.ymlrtd.project を作成し、Read The Docsプロジェクト名とその言語を指定する
  4. GitHub上でrtd-botを有効化する

注意点

  • いまのところ、Read The Docs側の設定項目(例えばドキュメントの場所など)には柔軟に追従できません。
  • 現バージョンのRead The Docsにおける「メンテナーの招待」は、「全権限の委譲」にほかなりません。不安な場合はご自身でProbotをホストいただけます。

技術的な工夫と、今後の開発の予定

このプロジェクトではCommitizenSemantic Releaseを導入しました。思っていたよりも使いやすく、またDependabotがすでにcommitizen風コミットコメントに対応していたため、特に導入に障害はありませんでした。MavenやGradleでも使えたら良いんですが、そこはまだハックが必要そうです。

Read The DocsのAPIはまだ機能不足が目立ちます。最近出たAPI v2でも認証機能すら無く、公開データへの読み取りアクセスしかできません。 今回はこの問題の回避にPuppeteerを使っています。つまり管理画面をNode.jsで操作しています。だいぶダーティハックですが、利用規約上も問題ないはずです。画面の更新には逐次追随する必要がありますが、過去の経験から言ってRead The Docsの画面はさほど大きく変更が入らないと思われます。

直近の予定としては、i18nには対応したいと考えています。他にも対応必要な設定があればROADMAP.mdに追記のPRを送ってください。

dockerでSonarQubeのインストールを楽にやる

クラスメソッドさんのブログでSonarQubeの紹介がされています。そちらの記事では記事の半分ほどを割いてインストール方法を説明していますが、dockerを使えばより楽に行えますのでその方法を紹介します。

dev.classmethod.jp

検証用のSonarQubeを立ち上げる

以下のコマンドで、組み込みデータベースを使用したサーバが立ち上がります。ユーザ名admin、パスワードadminでログインできます。 このコマンドは英文公式ページからの引用です。

$ docker run -d --name sonarqube -p 9000:9000 -p 9092:9092 sonarqube

なおalpineを使ったイメージもあるのですが、2018年8月1日現在でClassNotFoundErrorが出るなど不安定なようです。7.1-slpineなどのバージョンではなく、7.1などのバージョンの利用を推奨します。

PostgreSQLを使ったSonarQubeを立ち上げる

組み込みデータベースでの運用は検証用にのみ推奨されていますので、本番運用はRDBMSの利用が必要です。 以下のページにSonarQubeとPostgreSQLを立ち上げるdocker-compose.ymlが紹介されていますので、これを保存したディレクトリでdocker-compose upすればSonarQubeとPostgreSQLが立ち上がります。

docker-sonarqube/recipes.md at master · SonarSource/docker-sonarqube · GitHub

プラグインのインストールを自動化する

$SONARQUBE_HOME/extensions/pluginsディレクトリにプラグインの.jarファイルを保存することで、プラグインをインストールし有効化できます。 例えばSonarQube 6.7.4 LTSに sonar-findbugsとそれが依存しているSonarJavaをインストールするDockerfileは以下のようになります:

FROM sonarqube:7.1

RUN wget -P $SONARQUBE_HOME/extensions/plugins/ --no-verbose https://github.com/spotbugs/sonar-findbugs/releases/download/3.7.0/sonar-findbugs-plugin-3.7.0.jar && \
    wget -P $SONARQUBE_HOME/extensions/plugins/ --no-verbose https://sonarsource.bintray.com/Distribution/sonar-java-plugin/sonar-java-plugin-5.6.0.15032.jar

SpotBugsプラグインを元にしたSonarQubeプラグインを実装する方法

SpotBugsプラグインの実装方法には公式ドキュメントがありますが、SpotBugsプラグインをSonarQube上で実行するための手法はまだ固まっていません。最近Guava Migration HelperのSonarQubeプラグインのリリースに動いているので、要点をまとめておきます。

SonarQubeプラグイン実装の基本

まずSonarQubeの公式ドキュメントに目を通しておきます。特にMarketplaceでの公開を前提としている場合は、Plugin Keyの命名に制約があったり、SonarCloudの利用が必須だったりしますので、制約についてよく読んでおくと良いでしょう。

Mavenプロジェクトを作る

Gradleサポートは公式ではないので、Mavenを選択します。SpotBugsプラグインと同じプロジェクトで管理すると、メタデータ作成(後述)で手間がかからないのでおすすめです。私のプロダクトではSpotBugsプラグインとSonarQubeプラグインとをサブモジュールとして管理するプロジェクトを使っています。注意点は以下の通りです:

  • SonarQubeプラグイン<packaging>sonar-plugin</packaging>にする。
  • sonar-packaging-maven-pluginの設定に<basePlugin>findbugs</basePlugin><requirePlugins>findbugs:3.5</requirePlugins>を入れる。sonar-findbugs v3.5は初めてSpotBugsを導入したバージョンなのでこれ以降のバージョンを指定するのが良い。
  • SpotBugsプラグインが何らかのライブラリに依存している場合、普通のパッケージとshadedパッケージと両方を用意すると良い。 shadedはAntユーザやCLIユーザなど推移的依存が自動的に解決されない場合(プラグイン手配置が必要な場合)に便利。 shadedだけ用意すると、推移的依存が自動的に解決される場合に同じライブラリを複数回ダウンロードするリスクや、dependencyReducedPomによって依存先のメタデータが隠匿されてしまう(例えばライセンス管理がやりにくくなる)問題も生じる。

rule.xmlを生成する

SonarQubeはfindbugs.xmlやmessages.xmlを読まないので、SonarQubeが読める形式でルールに関するデータを提供する必要があります。私はこれをMavenプラグインで自動生成しています。ルールによってタグを変える必要がある大型プロジェクトじゃない限り、これで十分だと思います。

コードを書く

基本的にはPlugin.javaとRulesDefinision.javaの2つで足ります。以下がサンプル:

注意点は以下の通りです:

  • Context#createRepository()の第一引数は"findbugs"である必要がある。 それ以外の値だと、sonar-findbugsが検知してくれない その結果 findbugs-include.xml にBugが登録されないので、SpotBugsプラグインが解析に使われても結果一覧に出てこなくなる。

リリースする

あとはいつもどおりMaven Centralに公開した上で、SonarSourceコミュニティのフォーラムで申請すれば通るようです。私のプラグインはまだ申請中です:

JJUG CCC 2018 SpringでSpotBugs3.1系実装について話してきました

先週末に開催されたJJUG CCC 2018 Springに参加してきました。昨年に引き続き、SpotBugsに関する内容です。

20名ちょっとのエンジニアに参加いただき、3.1系実装で苦労しているところ、Java9対応が進まない理由などを話しました。Togetterはこちら

Maven Central Statisticsからもわかっていたことですが、まだFindBugsユーザのほうが多いですね。Java8移行を使っているならSpotBugsの方が安定&高速なので、ぜひ移行を検討いただきたいです。よくできていると好評のマイグレーションガイドもあります。

聴講したものの中では、アンカンファレンスが面白かったです。初めて参加したのですが、様々な立場の方がご自身の経験と考えをもとに意見を交換するのは参加していて楽しく感じます。こういう議論をもっと日頃からできると良いですね。また自分は参加しませんでしたが、海外登壇経験者のパネルディスカッションも面白かったようです。自分は海外在住なのにあまり参加経験がないので、そのうち行ってみたいところ。

チームビルディングのためにやったこと、できていないこと

これ↓読んで、自分の経験をまとめようと思ったのでメモ。

www.yutorism.jp

チームビルディング、ないし組織・オフィスの改善のためにやってきたことはけっこうある。反面、できていないこともかなりある。

やったこと、継続していること

社内技術勉強会

上海拠点設立時に董事長と話してやったのがこれ。せっかくCS専攻の人を集めたのだし、ポテンシャルある人ばかりなので、彼らが互いに刺激を与え合える機会を作ろうという狙いだった。当時は20名弱だったので、全員にスライドを使って企画意図を説明したのを覚えている。

最初は発表者が2,3名に偏ったり、開催時間が固まらなかったり(最初は朝開催を目指したが、結果的には夕方開催に落ち着いた)、発表が数週間連続でなかったりという問題も多かった。しかし結局は、私が異動でいなかった時期(1年間)も含めて6年間続けられている。継続するのが一番難しいので、これは普通に素晴らしいことだと思っている。

継続のコツは、やはりイベント自体を楽しいものだと思ってもらうこと、他の人を巻き込んで協力を得ることだと思う。魅力を理解してくれた数名が引き継いでくれたからこそ私が不在でもイベントが回ったし、今は自分が聞き込みや勧誘をしなくても社内交流促進の専門家が代わりに調べてくださっている。ので、最近の私はたまに発表するだけという立場。たぶん私が立ち上げ人ということを、新人は認識していないはず。

問題共有イベント

最近は拠点規模が大きくなって、拠点全体で何が起こっているのかを把握するのが難しくなってきた。また異なるチームで似たような問題をバラバラに解いているような状況も散見されるようになってきた。問題解決こそが仕事なのにこの状況は好ましくないだろうということで、従来人事評価時にやってきた成果発表とは別に、プロセスと問題とを拠点内で共有するイベントを立ち上げた。怒らないことを強調しないだけで、前述のイベントとほとんど同じ。

部署の壁を超えて数百人巻き込むので、コストが大きいことを個人的には気にしている。ので毎回アンケートで発表者と聴衆の両方から実際役に立ったのかフィードバックを得ているが、いまのところコストを成果が上回っている認識。今後も成果の評価と改善検討を続けていくつもり。

AMAイベント

これについては自分の上長が事業部で実践していたものをパクって上海に持っていっただけ。主に新人が持っているであろう疑問や、いわゆるhard questionを部長らが匿名(実名付記も可)で集めて一括で答える。文書化されてないルールや、歴史的経緯でそうなっているもの、(中国の)普通の会社でやっているのにやっていないこと(あるいはその逆)とかに関する質問が色々集まる。推測や疑問を検証できる機会を公式に作るだけで、教育やモチベートの切欠を作ることができる。問題回収と整理は非同期でできるので、複数人を一同に集めることもなく開催コストもそんなに高くない。

最初はQuestion Gathering Eventと呼んでいたが、最近AMAという言葉が身近で流行したので、今はAMAあるいはAsk Us Anythingと呼んでいる。

技術交流用WeChatグループ

WeChatでグループを作り、社員と元社員とでFOSSについて話す場としている。はてブと同じノリでURLをポンポン投稿する感じ。任意参加なので尖った技術者が集まりやすい。RustとかTaigaとかConduitとかはここでキャッチしている情報もある。新人には、興味を感じる分野を探す一助になっていればいいなと思っている。

MBO-S

これに関しては普通に目標管理の教科書を参考にやっている。変わったこともたいしてやってないはず。上長としては部の短期・中期目標(どのProblem Spaceにフォーカスするか)を明確に提示し、それぞれに固有名詞を付ける(Project FooBarとか)ことで、メンバー間交流が促進され挑戦・工夫がしやすい状態になるよう心がけている。自分のMBO-Sフォーマットは社内SNSで公開し、壁に貼って誰でも閲覧できるようにしている。

1on1

これも初めて6年になる。運用上工夫しているのは3点:

  1. 直接の部下(課長?)とは週次、間接的な部下とは月次で実施
  2. 時間を自由に使って良いことを前提として、聞きたいことリストをこちらから提示(情熱的に働けているか、やりたいことの妨げになっているのは何か、上長に期待しているのは何か、直近の全社集会について質問はあるか等)
  3. 1on1を受けてこちらがやることを、最後の時間でコミット

本当は2みたいな質問の提示は誘導に繋がるのでやらないほうが良いと思っているが、何も持ってこない人が散見されるので補助線として用意している。

参考にしている本は複数あるが、最近読んだのはフィードバック入門マネジャーの最も大切な仕事HIGH OUTPUT MANAGEMENTあたり。特にフィードバック入門のTeaching + Coaching = Feedbackという図式はわかりやすく応用がきく気がしている。

できていないこと、継続できなかったこと

ライトニングトークイベント

前述の社内勉強会の一環として、30分ずっとLTするようなイベントを考えたことがある。結果、3〜5分という短い時間で話し切ることに慣れさせることができずに終わってしまった。会社を一歩出ればLTの機会がたくさんある東京と違って、勉強会が少ない上海ならではの問題かもしれない。

輪読会、読書会

これが定着しない理由は明確で、私自身に成功体験がないから。どこかでちゃんと運営された読書会に参加して、感覚を身に着けたい。

今は本を一緒に読む代わりに、おすすめの記事や本を社内SNS等で発信している。今のところはCI/CDやMSAについて語る機会が多いので以下だが、随時アップデートしている。

休祝日のチームビルディングイベント

これは日本で開発合宿経験済みではあるのだが、自分が子持ちということやその他の事情から積極的にやる予定がない。上海の部下はともかく、日本の部下とはかなりやりにくいという事情もある。やる気と関心がある部下に、提案から丸投げている状態。

社外の人を巻き込んだ勉強会

これは1回だけやったことがあるが、会場と参加者の定期確保に失敗した。そもそも上海で定期的に勉強会を開催しているのがWiredcraftくらいなものなので、潜在市場はありそう。深センほどではないとしても、上海にはGoogleMicrosofteBayチームラボサイボウズも色々居るはずなので、ちゃんとツテを作って運用したい。

とりあえず現地日本人コミュニティに顔を出しつつ、上海のMeetup.comで定期的に参加できる勉強会を探していくつもり。