From 90d7fb2cfe8a370d20cf131994c6f3a2b52398d8 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 5 Oct 2021 16:49:56 -0700 Subject: [PATCH 1/2] doc: document considerations for inclusion in core Document the things that are considered when making the determination as to whether something should or shouldn't be in core. This does not (yet, at least) attempt to address *how* to include modules in core. (Should it be in the Node.js code base or vendored in from a separate repository?) It is limited to *whether* something should be in core or not. Closes: https://github.com/nodejs/TSC/issues/1041 --- doc/guides/modules-in-core.md | 52 +++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 doc/guides/modules-in-core.md diff --git a/doc/guides/modules-in-core.md b/doc/guides/modules-in-core.md new file mode 100644 index 00000000000000..5d43a9b22053e8 --- /dev/null +++ b/doc/guides/modules-in-core.md @@ -0,0 +1,52 @@ +# To be or not to be in core + +Should a module be in core? This question arises every so often. This document +explains things to consider when deciding whether a module should be in core or +not. + +## Strong arguments for including a module in core + +1. The module provides functionality that is standardized (such as a + [Web API][]) and overlaps with existing functionality. +2. The module can only be implemented in core. +3. The module can only be implemented in a performant way in core. +4. Developer experience is significantly improved if the module is in core. +5. The module will be widely used, have cross platform native code, and being in + core will avoid the need for an end-user compilation chain. +6. Part or all of the module will also be re-used or duplicated in core. + +## Strong arguments against including a module in core + +1. None of the arguments list in the previous section apply. +2. The module has a license that prohibits Node.js from including it in core + without also changing its own license. +3. There is already similar functionality in core and adding the module will + provide a second API to do the same thing. +4. A module (or/and the standard it is based on) is deprecated and there is + a non-deprecated alternative. +5. The module is evolving quickly and inclusion in core will require frequent + API changes. + +## Benefits and challenges + +When it is unclear whether a module should be included in core, it might be +helpful to consider these additional factors. + +### Benefits + +1. The module will receive more frequent testing with Node.js CI and CITGM. +2. The module will be integrated into the LTS workflow. +3. Documentation will be integrated with core. +4. There is no dependency on npm. + +### Challenges + +1. Inclusion in core is likely to reduce code merging velocity as the Node.js + process for code review and merging is more time-consuming than that of most + individual modules. +2. By being bound to the Node.js release cycle, it is harder and slower to + publish patches. +3. Less flexibility for end users. They can't update the module when they choose + without also updating Node.js. + +[Web API]: https://developer.mozilla.org/en-US/docs/Web/API From c5e35ada52a59347496881757ec559f97d47eed9 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 19 Oct 2021 21:35:54 -0700 Subject: [PATCH 2/2] fixup! doc: document considerations for inclusion in core --- doc/guides/modules-in-core.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/guides/modules-in-core.md b/doc/guides/modules-in-core.md index 5d43a9b22053e8..8cd7fc7647d983 100644 --- a/doc/guides/modules-in-core.md +++ b/doc/guides/modules-in-core.md @@ -11,9 +11,12 @@ not. 2. The module can only be implemented in core. 3. The module can only be implemented in a performant way in core. 4. Developer experience is significantly improved if the module is in core. -5. The module will be widely used, have cross platform native code, and being in - core will avoid the need for an end-user compilation chain. -6. Part or all of the module will also be re-used or duplicated in core. +5. The module provides functionality that can be expected to solve at least one + common use case Node.js users face. +6. The module requires native bindings. Inclusion in core enables utility across + operating systems and architectures without requiring users to have a native + compilation toolchain. +7. Part or all of the module will also be re-used or duplicated in core. ## Strong arguments against including a module in core