Proposal: Remove ESM/CJS duality from code samples in API docs
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- JavaScript
- Sterne
- 122k
- Forks
- 37.3k
- Ø Merge
- 4 T. 2 Std.
- Gemergte PRs (30 T.)
- 283
Beschreibung
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
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Überprüfe die Beispiele unter /doc/api und erfasse die Codeblöcke mjs und cjs, wobei du Fälle notierst, die speziell das CommonJS-Verhalten demonstrieren. Bestätige den Umfang und die Konvention ESM als Standard mit den Maintainers, bevor du geeignete Beispiele in js-Blöcke zusammenführst. Als abgeschlossen gilt die Aufgabe, wenn doppelte Beispiele entfernt wurden und CJS-spezifische Demonstrationen weiterhin korrekt sind.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- javascript
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Aktiv
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 45/100