Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

meta: considerations for new core modules #15022

Closed
wants to merge 6 commits into from
Closed

meta: considerations for new core modules #15022

Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9a17c71
meta: considerations for new core modules
jasnell Aug 24, 2017
101f84c
[Squash] Refine details based on feedback
jasnell Aug 25, 2017
41242d8
[Squash] Nit
jasnell Aug 25, 2017
479aeae
[Squash] Be forceful and assertive. Believe in yourself.
jasnell Aug 25, 2017
fbcd579
[Squash] I think we're getting closer.
jasnell Aug 25, 2017
00df632
[Squash] *Now* I think I've got it.
jasnell Aug 25, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions COLLABORATOR_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,24 @@ multiple commits. Commit metadata and the reason for the revert should be
appended. Commit message rules about line length and subsystem can be ignored.
A Pull Request should be raised and approved like any other change.

### Introducing New Modules

Semver-minor commits that introduce new core modules should be treated with
extra care.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add that they need to land with two CTC (or maybe TSC now) signoff, like any other breaking change.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would that be a should or a must?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's a must. It's serious business: we are adding new API that we will need to maintain to core. Removing those is hard, so the CTC should be notified to weight in.


The name of the new core module should not conflict with any existing
module in the ecosystem unless a written agreement with the owner of those
modules is reached to transfer ownership.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We need to add a statement like: "if the new module name is free, a collaborator should park it as soon as possible, linking to the pull request that introduces the new module".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh right, good point

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you still have not added this.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oy... heh... one sec


New core modules must be landed with a [Stability Index][] of Experimental.
Pull requests proposing new core modules must still be marked semver-minor.
New core modules must remain Experimental until a semver-major release.

It is recommended to give PRs introducing new core modules at least one week
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Make it more forceful and concise:

Pull requests introducing new core modules must be left open for at least one week for review.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

for review. For new modules that involve significant effort, non-trivial
additions to Node.js or significant new capabilities, an
[Enhancement Proposal][] is recommended but not required.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is confusing to me. (For example, it implies that new modules typically are trivial additions to Node.js.)

How about this?:

If a new module has a large API surface, requires extensive changes to Node.js core, or adds extraordinary new functionality, open an [Enhancement Proposal][].


### Deprecations

Deprecation refers to the identification of Public APIs that should no longer
Expand Down Expand Up @@ -642,3 +660,5 @@ release. This process of making a release will be a collaboration between the
LTS working group and the Release team.

[backporting guide]: doc/guides/backporting-to-release-lines.md
[Stability Index]: https://github.com/nodejs/node/pull/doc/api/documentation.md#stability-index
[Enhancement Proposal]: https://github.com/nodejs/node-eps