Proposal: Remove ESM/CJS duality from code samples in API docs
まだ誰も着手していません。
- 主要言語
- JavaScript
- スター
- 122k
- フォーク
- 37.4k
- 平均マージ
- 4日 3時間
- マージ済み PR(30日)
- 272
説明
Since the introduction of ESM to Node.js core, we have been providing togglable ESM/CJS code examples in the API docs.
These examples differ only in the lines of code containing core imports, but the entire codeblocks need duplicating due to the limitations of the web renderer, leading to whole reams of duplicated cruft across /doc/api. The documentation space is extremely patchy as to which examples are just ESM, just CJS, or both. We occasionally get very kind contributors submitting PRs to double-up existing CJS-only code examples, but these are not good uses of reviewer time.
Almost invariably, it is incredibly obvious as to how to convert an ESM import from a builtin module into a CJS import, or vice versa.
I suggest that we:
- get rid of ```mjs and ```cjs blocks in favour of a single ```js block
- canonicalise ESM imports as the example paradigm of choice, unless a example is specifically demonstrating something CJS-specific
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
/doc/api 配下の例を確認し、mjs と cjs のコードブロックを一覧化して、CommonJS の動作を特に示しているケースを記録します。対象範囲と ESM をデフォルトとする規約を maintainer に確認してから、対象となる例を js ブロックに統合します。重複した例が削除され、CJS 固有のデモンストレーションが正確なまま維持されていれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- javascript
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 活発
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 45/100