Skip to content

Commit

Permalink
doc: document considerations for inclusion in core
Browse files Browse the repository at this point in the history
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: nodejs/TSC#1041
  • Loading branch information
Trott committed Oct 15, 2021
1 parent 881174e commit 62db5d8
Showing 1 changed file with 44 additions and 0 deletions.
44 changes: 44 additions & 0 deletions doc/guides/modules-in-core.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# 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.

## 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

0 comments on commit 62db5d8

Please sign in to comment.