こんにちは、エムスリーエンジニアリングGの榎田です。趣味は数学とゲームです。4連休で初代 FF13 のストーリーが終わったので、微積分の勉強ノートを書く傍らロングイを狩るかどうか悩んでいます。

業務では医療系ポータルサイト m3.com の開発・運営を担当する Unit4 というところにいます。その中でも普段は Docpedia というサービスの開発担当をするチームにいます。今日は、その Docpedia チームが新規メンバーのオンボーディングを担う役割を持っていること、ならびにその役割をより良く果たせるために入れた技術的な工夫について紹介します。Docpedia のサービスとしての話は書かないので、そちらに興味がある方はこちらの記事などをご覧ください。

オンボーディングとしてのチーム
環境差分をなくして快適に
- before
- after
We are hiring!

オンボーディングとしてのチーム

弊社では「全員採用」の名のもと、採用に力を入れています。それはエンジニアリンググループも例外ではありません。その結果もあってエンジニアチームは拡大を続けており、今や Unit4 だけでも15人以上のメンバーがいます。

新しくどなたかを採用した場合、その人を受け入れ、その人に開発プロセスに慣れてもらうオンボーディングのプロセスは不可欠です。ここで、

開発プロセスに慣れてもらう

と一言で書いたのですが、実際にはここに様々な暗黙知があります。たとえばローカルで開発環境を立ち上げる際にも、いろいろなところでハマる可能性があります。Readme にちゃんと書いてあればよいのですが、環境構築を二度も三度もやることはほぼないので、うっかり更新されないことが多々発生します。そうするとハマりポイントがそのままになります。

今の Unit4 では、Docpedia チームがそのオンボーディングの役割を担う場合がよくあります。そんな Docpedia チームでも、ハマりポイント自体はあります。しかし、できるだけそのようなポイントを減らして共有したり共通化したりを試行錯誤しています。例えば実際の環境構築時はハマったらとりあえず zoom をつないで都度解決したり、解決した内容が Readme に反映できる場合はしたり、使うソフトのバージョンは Readme に明記したり、といった具合です。

環境差分をなくして快適に

とはいえ、そもそも落とし穴が発生しないようにできるならそのほうがいいです。上記で挙げた中で言えば、たとえば使うソフトのバージョンをいちいち気にするのは煩雑なので、勝手に揃うのが理想です。言い換えるとマシンごとの環境差分ができにくくする仕組みがあるとよい、ということです。

Docpedia チームでもそのような「環境差分ができて困る場合があったので、そもそも環境差分ができない仕組みをつくった」事例があるのでご紹介します。Docpedia では一部のコードを openapi を用いて自動生成しているのですが、その部分のセットアップに関する改善です。自動生成の仕組みの詳細は以下の記事をご覧ください。

www.m3tech.blog

before

この自動生成をする部分の Readme は以下のようにしていました；

// Readme.md
## 事前作業

作業PCに以下を入れておく。

- OpenAPI Generator (バージョンによって生成されるコードに違いがあるのでバージョンを固定する)
- ktlint

$ npm install @openapitools/openapi-generator-cli@1.0.7-4.1.0 -g
$ brew install ktlint

## API 更新時

以下のスクリプトを実行する。

// brew install ktlint をしていないと失敗する
$ ./script/generate_kotlin_code.sh

実際の処理は以下のとおりです。https://openapi-generator.tech/docs/file-post-processing/の機能を使っています。

// 実際のコマンドは他にも色々オプションあるけど省略
// バックエンドは KOTLIN_POST_PROCESS_FILE で指定したフォーマットを用いて後処理をする
export KOTLIN_POST_PROCESS_FILE="$(which ktlint) -F"
openapi-generator generate --enable-post-process-file

ポイントは which ktlint の結果を使うことです。つまりローカルマシンに入れた ktlint のバージョン次第ではフォーマットの仕方が変わります。実際、新しくメンバーが増えたタイミングで毎回「なぜか Pull Request に改行だけの diff が出ますね…」とコメントをして原因を調べてバージョンを揃えて…ということをしていました。他にも、Readme で openapi-generator のバージョンについて注意しています。生成されるコードがバージョンによって違って困った、ということがあったからです。

after

これは改善の余地があると思ったので、あれこれ試行錯誤して以下のように変えることにしました。

使う openapi-generator-cli は package.json で指定する。
指定した openapi-generator-cli は npm install でローカルインストールし、Docpedia ディレクトリの外を汚さない。
後処理の ktlint は gradle plugin を使う。バージョンは build.gradle で指定する。特に which ktlint の結果を参照しない。

今回の話に関係ある部分のみを切り出せば以下のようになります。

// script/package.json で npm install の結果を固定
// package-lock.json も別途生成して commit 済
{
  "name": "docpedia-generate-openapi",
  "version": "1.0.0",
  "description": "開発に必要な各種 script をここにまとめて置いている。",
  "main": "index.js",
  "dependencies": {
    "@openapitools/openapi-generator-cli": "^2.2.2"
  },
  "scripts": {
    "generate": "./generate_kotlin_code.sh"
  },
}

// script/openapitools.json で openapi-generator-cli のバージョンを固定
{
  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
  "spaces": 2,
  "generator-cli": {
    "version": "4.1.0"
  }
}

// build.gradle で ktlint のバージョンを固定
buildscript {
    dependencies {
        classpath("org.jlleitschuh.gradle:ktlint-gradle:9.1.1")
    }
}

// 実際の実行ファイル script/generate_kotlin_code.sh
npx openapi-generator-cli generate
pushd "${BASE_DIR}/.."
./gradlew clean ktlintFormat
popd

Readme は以下のようになりました。注意書きが減って読みやすくなったと思います。また、いまのところ「これでハマった…つらい…」という話も聞かないので、目的は達成されていると思います。仕事がつらくないというのは大事なことです。

## 事前作業

$ cd script
$ npm install

## API 更新時

$ cd script
$ npm run generate

更に、実際にこの改善をする前後で、すでにいたメンバーからも「実は自分の手元でも diff が出たことがあり、あれこれ回り道して無理やり解決してたんですが、それがなくなって良かったです」という意見がありました。オンボーディングが快適なプロダクトを目指すという文脈でこの取り組みを挙げましたが、実際には今いるメンバーの開発体験にとっても良いことであるとわかったのも嬉しいポイントです。