スクリプト：APIの破壊的変更の対策
Issue #1042
closed
今回のv38.3=>v38.4(あるいはv39.0?)へのアップデートではもちろん、今後のアップデートでお願いすることは
1. 動作の変更がないにもかかわらずクラスや命令などの「名前だけ」を変更することは絶対にしない。
2. 機能の削除/統合に伴うAPIの「廃止」への対応は、命令やクラス/Enumやそのプロパティ/メソッドを何も実行しなかったり無意味な値を返すような「同名のダミー」として再実装する形で行い、実行すると必ずエラーとなる「API自体の削除」は絶対に行わない。
3. 引数や戻り値の変更など、APIの「変更」は新しい命令、クラス/Enum、プロパティ/メソッドを「新しい名前で新設」し、旧APIはこの新APIのラッパーとして再実装するなどして必ず残す。
というように「下位互換性」の維持を徹底することと、
4. Canary版の変更履歴に最終の正式版からのAPIの変更を必ず記述する。
5. 次期の正式版のAPI仕様が決定したら、遅くとも正式版バイナリのリリースの1ヵ月前に公式サイト上に発表し、スクリプト開発側に「猶予期間」を与える。
6. 変更履歴の記述において、上記1～3の下位互換性維持の対策が取れなかったAPIの変更に関しては「破壊的変更」のカテゴリにまとめて記述し、
6.A 下位互換性の維持ができなかった理由。
6.B スクリプト開発者側での対処方法。
を詳しく説明する。というようにユーザー/管理者への配慮を行うことです。
せめて、APIの破壊的変更によるエラーの取り扱いに関して
11. 代替のAPIの紹介などの具体的な修正方法の提示。
12. エラーの発生個所の行/カラム番号の表示。
13. メッセージをCtrl-Cなどでクリップボードにコピー可能にする。
14. try-cacheで補足可能にする。
15. APIの破壊的変更によるエラー限定で、エラーを無視してスクリプトを継続して握りつぶしたエラーオブジェクトの配列を生成する機能を新しく実装する。
といった改善をしてもらえれば助かります。どうかよろしくお願いいたします。
Comments (11)
-
reporter
-
reporter
- 代替のAPIの紹介などの具体的な修正方法の提示。
実装済みだが、Canary0518で機能していない。JINTを更新した影響でアプリ側まで例外が送られていないようだ。要調査。
- エラーの発生個所の行/カラム番号の表示。
取得できるのか？要調査
- メッセージをCtrl-Cなどでクリップボードにコピー可能にする。
現状メッセージはトースト通知だが、メッセージ表示方法を含めて再検討
- try-cacheで補足可能にする。
できそう。要調査
- APIの破壊的変更によるエラー限定で、エラーを無視してスクリプトを継続して握りつぶしたエラーオブジェクトの配列を生成する機能を新しく実装する。
動作が不完全なものになるので、通常の機能としてはむずかしい。デバッグモードとして実装できる？
-
reporter
1.動作の変更がないにもかかわらずクラスや命令などの「名前だけ」を変更することは絶対にしない。
なるべくしないようにしたいですが、可能性はあります。誤字の修正や他のプロパティとの不一致が際立つときなどです。
2.機能の削除/統合に伴うAPIの「廃止」への対応は、命令やクラス/Enumやそのプロパティ/メソッドを何も実行しなかったり無意味な値を返すような「同名のダミー」として再実装する形で行い、実行すると必ずエラーとなる「API自体の削除」は絶対に行わない。
ダミーの実装は結局の所意図しない動作になるため、基本的にエラーとする。実装するならデバッグモード等でできる範囲で。
完全なダミー実装は、それを含めた互換性維持が膨れ上がる一方になり、その作業はやりたくない。
3.引数や戻り値の変更など、APIの「変更」は新しい命令、クラス/Enum、プロパティ/メソッドを「新しい名前で新設」し、旧APIはこの新APIのラッパーとして再実装するなどして必ず残す。
同上
4.Canary版の変更履歴に最終の正式版からのAPIの変更を必ず記述する。
Canary版は機能自体の変更が大いに有り得るため、通知にあまり意味がない。Canary版の更新履歴は自動生成している。Canary版までドキュメント作成の手間を掛けるのはやりたくない。
5.次期の正式版のAPI仕様が決定したら、遅くとも正式版バイナリのリリースの1ヵ月前に公式サイト上に発表し、スクリプト開発側に「猶予期間」を与える。
Beta版の公開のお知らせは今後は行う予定。Beta版ではドキュメントも含めて正式版を想定したものとなる。ただ、期間は１～2週間かなあ。
6.変更履歴の記述において、上記1～3の下位互換性維持の対策が取れなかったAPIの変更に関しては「破壊的変更」のカテゴリにまとめて記述し、
6.A 下位互換性の維持ができなかった理由。
6.B スクリプト開発者側での対処方法。できる範囲で。6Bとか自動生成できれば理想。
-
reporter
- edited description
-
reporter
12.エラーの発生個所の行/カラム番号の表示。
文法エラーの行番号は現在でも取得できているが、実行時例外は取得できない。
GetLastSyntaxNode() は最新版では非公開のようだ。デバッグ用仕組みを構築中なのかも？ -> https://github.com/sebastienros/jint/pull/821
-
reporter
- changed title to スクリプト：APIの破壊的変更の対策
-
reporter
GetLastSyntaxNode() は 3.0.0-beta-1914 では使用できるので、当面このバージョンとする。
-
reporter
- スクリプト：エラーメッセージに行番号表示
- スクリプト：スクリプトのエラーレベル設定追加
- スクリプト：エラーメッセージをコンソールに出力
- スクリプト：コンソール非表示中にログをある程度蓄えるようにした
(refs
#1042)
→ <<cset 2254d971ae86>>
-
reporter
14.try-cacheで補足可能にする。
3.0.0-beta-1914 ではインデクサからの例外がキャッチできないため、保留とする。
-
reporter
- スクリプト：破棄されたメンバーのリストをスクリプトヘルプに自動生成するようにした (refs
#1042)
→ <<cset 18fecb00aa11>>
- スクリプト：破棄されたメンバーのリストをスクリプトヘルプに自動生成するようにした (refs
-
reporter
- changed status to closed
- Log in to comment
完全な対策はおこなわない。維持するコストと私のやる気の問題です。
できる範囲で対策を行う。