【package】npm-check-updatesで一括更新すると、壊れた原因が分からずにハマるので、patchから慎重に上げています
はじめに
ncuの基本的な使い方はよく見かけますが、ncuを使用した上でご安全にバージョンアップする手順はあまり見かけないので、言語化して記事にしてみました。
ローカル環境でのバージョンアップ作業を中心に解説します。プルリクエスト・ステージング環境以降の作業は割愛しますのでご了承ください。
対象
-
ncuをよく使っている方向け。-
ncuの基本操作は理解している前提です。 - 自動テストが整備されている前提です。
- 警告は常に出力されるようにあらかじめ設定しておきましょう。
-
前提知識
前提としてセマンティックバージョニングの理解が必要です。短い文章なので読み飛ばさず、心の中で音読するくらいの気持ちで読みましょう。
ごく稀にセマンティックバージョニングに則らないお行儀の悪いパッケージがあります（メジャー0の場合は別、先述のリンク先を参照）。そのような例外的なパッケージには本記事では触れませんが、もし遭遇したら変更内容を見極め、慎重に対応してください。
アップグレード手順
パッチバージョンを上げる
パッケージをバージョンアップする
後方互換性を保ったバグ修正のみなので、パッチバージョンを上げただけで動かなくなるという事象は考えにくいです。
まずは以下のコマンドを用いて、ncuで表示されるパッケージを減らしていきます。
ncu -u --target patch
npm install
自動テストの通過を確認する
私は自動テストで特に問題が起きていなければ、次のステップに進んでしまっています。
強いていえば、不安なときは手動で軽く確認を行っているかもしれません。アプリの重要な機能を担っているパッケージ、後からだとデバッグが大変そうなパッケージなんかを、なんとなく嗅ぎ分けて確認している気がします。
やはり不具合が起きる方が稀なので、ここにコストをかけるくらいなら、次に進んでから異常があれば戻るくらいでもいいかと。もちろん余裕があれば確認した方が良いでしょう。
マイナーバージョンを上げる
パッケージをバージョンアップする
マイナーバージョンでは機能の追加や廃止が取り込まれます。
以下のコマンドを用いて、ncuで表示されるパッケージを減らしていきます。
ncu -u --target minor
npm install
追加された機能を確認する
機能追加についてはバージョンアップ後に別枠で、新機能への移行やリファクタリングの検討をおすすめします。
使用箇所が多い場合、一緒に対応すると差分が大きくなりがちです。またロードマップで後継機能への移行が決まっているもの、新しい機能を使えばよりスッキリ書けるものなど、見直しをかけた方がいいポイントも出てきます。
廃止予定の機能を確認する
機能廃止については非推奨の警告(Deprecated Warning）が大量に出ることもあるため、極力同時に修正を進められると理想的です。プロジェクトの状況次第ですが経験上、バージョンアップを優先して一気に対応してしまった方が、結果的に早く安く済みます。
自動テストが通るようにする
まずはテストが通るか確認します。
次に警告が表示されないか確認します。警告の撲滅がマイナーバージョンアップの主な作業です。一つずつエラーメッセージを頼りに修正していきます。
メジャーバージョンのパッケージを確認する
ここではまだ上げません。まずは残りのパッケージを確認します。
ncu
この時点で表示される項目は、ある程度減っている筈です。もし大量に出力されているとしたら、それは「保守をサボったツケ」なので甘んじて受け入れましょう。
次にこれらのパッケージを関連ごとに分類します。
- ESlint関係（本体・プラグインなど）
- Prettier関係（本体・プラグインなど）
- SCSS（Stylelint, Sass, PostCSS, etc...）
- 自動テスト関係（Cypress, Jest, etc...）
以降の作業は分類単位で進めていきます。影響が少ない場合は大雑把に分類しても構いませんが、自動テスト関係のアップデートと、その他のアップデートとは明確に分けて対応しましょう。
同時にバージョンを上げての修正は避けてください。自動テスト自体が動かなくなっているのか、アプリ側が動かなくなっているのか、識別が面倒になります。両方同時に修正した結果、自動テストが意図せず通過してしまうことも避けたいです。
メジャーバージョンを上げる
以降の作業は分類単位で進めていきます（2回目）。
パッケージをバージョンアップする
メジャーバージョンには破壊的変更が含まれます。
ncu -u A B C ...
npm install
--filter, --rejectなどのオプションを使うと、柔軟に対象を絞れます。詳しくはncu -hを参照してください。
アプリが動かなくなる可能性があります。互換性のない変更のあったAPIが偶然プロジェクトで使われていなければ、何事もなく終わるというだけです。まずは軽く動かしてみて、自動テストや動作確認でエラーが出ていないか見てみましょう。
破壊的変更を詳しく確認する
対象パッケージのリリースノートやドキュメントを確認し、変更内容を把握します。
- GitHubのRelease
- CHANGELOG.md
- 公式ドキュメントの移行ガイド
体感になりますが、エラーログをいきなり検索するよりも、事前に変更内容を頭に入れてからの方が楽な気がします。有名なライブラリであれば技術ブログで丁寧に解説されていることがあるので、そちらを参照しても良いでしょう。
設定ファイルの差分を反映する
メジャーバージョンアップの際、
- プロジェクト新規作成コマンドで生成されるファイルの差分
- 設定ファイル生成コマンドで生成されるファイルの差分
- ドキュメントに変更がある場合は、最新の書き方への移行
これらの作業を合わせて行っておきます。途中参画のプロジェクトではこの作業を行っていないことが多いのですが、差分が山のように出てきて追いつくのが大変です。
開発は自動生成されたファイルを起点とし、カスタマイズしながら進めていくものです。この起点ファイルはバージョンアップと共に変更されていき、古いプロジェクトでは差分が多くなっていきます。これを補正・修正し近付けておくと、デバッグもバージョンアップもやりやすくなります。
自動テストの通過を確認する
まずはテストが通るか確認します。ここでいう「テストが通る」は警告も表示されない、という意味です。原因を一つひとつ潰していきます。
動作確認を行う
手動でガッツリ動作確認を行います。最後は人の目で必ず確認しましょう。
おわりに
駆け足になりましたが、少しでもアップデート作業に不安がある方の助けになれば幸いです。
Discussion