この記事は公式アナウンス "End-of-Life for Built-in JSDoc Support in ESLint" の翻訳です。
ここ数年で ESLint プロジェクトのサイズとスコープは増大しました。もともとは単一の実行可能パッケージで構成されていましたが、今や複数のパーサーやユーティリティを含む多数のパッケージから構成されるプロジェクトへ成長しました。プロジェクトは成長しましたが開発チームの規模はそれほど大きくなく、全員がボランティアである開発チームがこのプロジェクトをメンテナンスしていくために、厳しい決定を下す必要がありました。
最近のレビューの一環として、ESLint プロジェクトでの JSDoc の組み込みサポートを廃止することを決定しました。 この投稿には、その決定の詳細と次に起こることが含まれています。
現在の JSDoc サポート
現在の ESLint の JSDoc サポートは以下のルールと API から構成されます。
- Doctrine コメント パーサー
- require-jsdoc ルール
- valid-jsdoc ルール
- SourceCode#getJSDocComment() メソッド
特に、ESLint の他の部分を維持するために必要な努力と比較して、Doctrine とvalid-jsdoc ルールを維持するために多くの時間を費やしていました。本日 (訳注: 2018/11/27) より、上記 4 項のサポートを廃止します。
サポート廃止が意味すること
今後 数週間のうちに以下のことを実施します。
- Doctrine コメント パーサーのリポジトリは凍結されます。2週間前にリリースされた v3.0.0 が最後のメジャーリリースになります。完全にメンテナンスを停止する前に 2,3 の小さな更新が必要かもしれませんが、機能追加やバグ修正はもう行われません。ただし、Doctrine は信頼できる状態にあるので、誰かが Doctrine をフォークして JSDoc コメントパーサーを開発したい場合は、きっとうまく行くでしょう。
- require-jsdoc と valid-jsdoc ルールは非推奨になります。私たちのルール非推奨ポリシーに従い、これらのルールはすぐには削除されませんが、機能追加やバグ修正は行われません。将来のメジャーバージョンアップの際に削除される可能性があります。
- SourceCode#getJSDocComment() メソッドは非推奨になります。今後、このメソッドに関する機能修正やバグ修正は行われません。将来のメジャーバージョンアップの際に削除されます。
実際にいつ頃 実施されるかを知るためには、今後のリリースノートをご確認ください。
推奨する移行先
引き続き ESLint で JSDoc コメントをチェックしたい場合、コミュニティによって維持されている eslint-plugin-jsdoc プラグインを利用することを推奨します。このプラグインは非推奨になったコアルールより JSDoc に特化している複数のルールを保持しており、ほとんどのプロジェクトにフィットするはずです。
FAQ
Doctrine のために新しいメンテナを探さなかったのは何故ですか?
私たちが Doctrine のための新しいメンテナを探さないことにした理由はいくつかあります。
まず、パッケージが広く使用されている割に、ESLint 開発チームの外からの貢献はほとんどありませんでした。いくつかのパッケージは外部の貢献者から多くの注目を集めているので新しいメンテナを見つけるのは簡単かもしれませんが、Doctrine はそうではありませんでした。
第二に、Doctrine は JS Foundation の一部であるため、メンテナンスを引き継ぐということは、JS Foundation に関与することを意味します。単一のメンテナがこれを採用することに決めた場合、それはあまりにも大きなオーバーヘッドになる可能性があります。
毎週 700 万回近いのダウンロードが行われていたため、既存のユーザーのためには、新しいメンテナを探すことよりも Doctrine プロジェクトを凍結することのほうが良いと思います。私たちは、既存のメンテナンス方法を引き継ぐよりも、Doctrine をフォークして新しいプロジェクトを始める方が、Doctrine の維持に関心のある新しいメンテナにとって良い選択肢だと信じています。
(訳注: 同日に話題になった、event-stream のメンテナンス引き継ぎに伴うセキュリティ インシデントを念頭に置いた文章です)
既存の JSDoc ルールを削除せずにメンテナンスを停止するのは何故ですか?
eslint-plugin-jsdoc プラグインに移行するための じゅうぶん な期間を設けるためです。私たちは、ユーザーに設定ファイルの更新を要求する回数を最小限に抑えたいと考えています。既存の JSDoc ルールを使用可能にしながら非推奨にすることで、ユーザーが徐々に移行できるようにしながら、開発チームのリソースをプロジェクトの別の部分に割り振ります。
他の質問がある場合は?
メーリングリスト で質問してください。
(訳注: 日本語で質問するには、こちらのリポジトリに Issue を作るか、日本語チャットルームをご利用ください)