meta: considerations for new core modules #15022

jasnell · 2017-08-24T22:25:23Z

Trott · 2017-08-24T23:03:32Z

COLLABORATOR_GUIDE.md

+Semver-minor commits that introduce new core modules should be treated with
+extra care.
+
+* First, the name of the new core module should not conflict with any existing


Nit: Remove First, .

There's also singular/plural disagreement in this sentence. Here's what I'd write:

The name of the new core module should not conflict with an existing module in the ecosystem unless there is an agreement with the owner of the existing module to transfer ownership.

Trott · 2017-08-24T23:06:32Z

COLLABORATOR_GUIDE.md

+* First, the name of the new core module should not conflict with any existing
+  module in the ecosystem unless an agreement with the owner of those modules
+  is reached to transfer ownership.
+* PRs that introduce new core modules must be landed as semver-minor commits.


I think this is unnecessary to state. Any new feature must be landed as semver-minor. If you're trying to say that even landing as Experimental is semver-minor (which I agree it should be), put that in with the statement about it needing to be Experimental first.

Trott · 2017-08-24T23:07:25Z

COLLABORATOR_GUIDE.md

+  is reached to transfer ownership.
+* PRs that introduce new core modules must be landed as semver-minor commits.
+* New core modules must be landed initially as `Experimental` and must go
+  through at least one release cycle before being moved out of experimental.


The term "release cycle" is probably vague to a lot of people.

So, yeah, putting my comments on the second and third bullet points together, maybe consolidate them into this single bullet point:

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.

Trott · 2017-08-24T23:08:37Z

COLLABORATOR_GUIDE.md

+* New core modules must be landed initially as `Experimental` and must go
+  through at least one release cycle before being moved out of experimental.
+* It is recommended to give PRs introducing new core modules more time for
+  review than the typical 48/72 hour review used for other commits.


Suggest a concrete time framer here. I'd go with this:

Pull requests introducing new core modules should remain open for one week rather than the usual 48-hour/72-hour review period for other pull requests.

I would suggest longer.... maybe even up to a month?

Maybe phrase it as a minimum? (open for at least one week)

I actually agree with @jasnell as this would probably have already prevented some trouble. Landing a new module should normally not be urgent.
One alternative might also be smth like At least one week without anyone requesting any further changes.?
And I would not make it a recommendation but mandatory with a optional fast path through a decision of the CTC/TSC?

I think it should be possible for collaborators to pick an appropriate timeframe, even without a fixed rule. One week as a minimum sounds good, but in any case the gist of it will be “if your PR is large/has profound impact, wait until people have had a fair chance to review & assess it”

Please explain why we don't want to go the EPS route. If a new module isn't a major addition I don't know what is.

EPS is an ok for speculative large changes but it's really hasn't been that successful of a process over all. Having a concrete pr available, with real code, real tests, real documentation is far easier to review and look at to determine if this is something we want. For instance, Bradley's ESM pr has been a thousand times for valuable than the endless noisy threads in the EPS repo on it. Same goes for the efforts that led to N-API, URL, Inspector, etc. Yes, some discussion in EPS can be helpful but gating whether or not a semver minor can land based on that seems far too unnecessarily heavyweight of a process and, frankly, discourages innovation significantly. I'd definitely be -1 to requiring EPS and have, on several occasions, even considered proposing removing it.

@addaleax ... "at least one week" sounds good to me but I would point out that the issue that led to me creating this issue in the first place (Jeremiah's concern that I landed the perf_hooks stuff too fast) meets all of the criteria discussed so far in this thread so I'm not sure if it's sufficient to make everyone comfortable. There needs to be a good balance so that a good compromise can be reached.

cjihrig · 2017-08-25T15:09:47Z

COLLABORATOR_GUIDE.md

+Semver-minor commits that introduce new core modules should be treated with
+extra care.
+
+* First, the name of the new core module should not conflict with any existing


I assume there should be an email, GitHub comment, or some other paper trail that shows the agreement with the existing module owner?

something along those lines yes.. I'm not sure how prescriptive we need to be with it.

jasnell · 2017-08-25T15:26:53Z

Updated based on feedback.

@cjihrig ... I clarified that the agreement with the existing module author should be written
@Trott and @addaleax ... I've made the time frame at least one week
@AndreasMadsen ... I've added a recommendation to use EPS under certain conditions

PTAL

addaleax · 2017-08-25T15:43:12Z

COLLABORATOR_GUIDE.md

+
+It is recommended to give PRs introducing new core modules at least one week
+for review. For new modules that involve significant effort, non-trivial
+additions to Node.js or significant new capabilities, an [EPS][] is


teeny tiny nit: EPS is plural, EP is the singular ;)

heh... sigh. Should I just change it to "Enhancement Proposal"?

Trott · 2017-08-25T20:40:29Z

COLLABORATOR_GUIDE.md

+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


Make it more forceful and concise:

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

Trott · 2017-08-25T20:47:39Z

COLLABORATOR_GUIDE.md

+Pull requests introducing new core modules must be left open for at least
+one week 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.


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][].

Trott

LGTM with or without my last suggestion.

mcollina

LGTM with my two comments adressed.

mcollina · 2017-08-25T22:49:45Z

COLLABORATOR_GUIDE.md

+
+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.


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".

oh right, good point

I think you still have not added this.

oy... heh... one sec

mcollina · 2017-08-25T22:51:15Z

COLLABORATOR_GUIDE.md

+### Introducing New Modules
+
+Semver-minor commits that introduce new core modules should be treated with
+extra care.


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

Would that be a should or a must?

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.

AndreasMadsen · 2017-08-25T22:57:39Z

EPS is an ok for speculative large changes but it's really hasn't been that successful of a process over all. Having a concrete pr available, with real code, real tests, real documentation is far easier to review and look at to determine if this is something we want. For instance, Bradley's ESM pr has been a thousand times for valuable than the endless noisy threads in the EPS repo on it. Same goes for the efforts that led to N-API, URL, Inspector, etc. Yes, some discussion in EPS can be helpful but gating whether or not a semver minor can land based on that seems far too unnecessarily heavyweight of a process and, frankly, discourages innovation significantly. I'd definitely be -1 to requiring EPS and have, on several occasions, even considered proposing removing it.

I guessed that was the reason. Personally, I disagree, when I look at PEP (Python Enhancement Proposal) I'm always impressed by the level of detail and thought that goes into pretty much any major feature. It is super helpful to learn about the thought process that went into the feature. I think we can learn a lot from them.

But if EPS is something we want to discourage, then we should change the EPS guide lines or deprecate the approach completely. But a minimum requirement for any new major feature should be to put it on the CTC agenda, even if there are no disagreements. That would have made any concerns in this cause quite obvious. This is effectively equivalent to the EPS approach, but with less documentation and more code.

jasnell · 2017-08-25T23:01:19Z

@AndreasMadsen ... that's fair :-)

We've been actively moving away from putting things on the ctc-agenda label in favor of a more async decision making process using ctc-review and only putting exceptions on ctc-agenda. It's been working rather well so far. So how about this, we keep the minimum one week, we require two CTC members to sign off (as @mcollina suggests) and we require that the issue is flagged with ctc-review during that time....

(Of course, that's in addition to it landing as Experimental)

jasnell · 2017-08-25T23:12:11Z

Ok, take a look now! I think I've captured your feedback @AndreasMadsen and @mcollina :-)

mcollina

LGTM

AndreasMadsen

LGTM

Especially the "ctc-review label" part is important to me.

As for how we should deal with pref_hooks specifically, I will defer that to @Fishrock123. It is clear to me that @Fishrock123 was against the PR and if a collaborator is against a PR then the CTC should be involved, which it wasn't. Mistakes were made, that happens and is fine, but we have to reevaluate perf_hooks as well.

PR-URL: #15022 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com> Reviewed-By: Andreas Madsen <amwebdk@gmail.com>

jasnell · 2017-08-29T04:16:38Z

Landed in 397dbab

targos · 2017-08-29T05:46:29Z

Should we notify all collaborators about this change?

jasnell · 2017-08-29T16:47:03Z

ping @nodejs/collaborators ... fyi

jkrems · 2017-08-29T17:39:59Z

COLLABORATOR_GUIDE.md

+module in the ecosystem unless a written agreement with the owner of those
+modules is reached to transfer ownership.
+
+If the new module name is free, a Collaborator should register a placeholder


Should we commit to adding (or allowing for) polyfills to be published for older versions of node under that name? Or is that out of scope for this generic document and would be discussed case-by-case?

I'd say that's out of scope

PR-URL: nodejs/node#15022 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com> Reviewed-By: Andreas Madsen <amwebdk@gmail.com>

PR-URL: nodejs#15022 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com> Reviewed-By: Andreas Madsen <amwebdk@gmail.com>

PR-URL: #15022 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yuta Hiroto <hello@about-hiroppy.com> Reviewed-By: Andreas Madsen <amwebdk@gmail.com>

meta: considerations for new core modules

9a17c71

nodejs-github-bot added the doc Issues and PRs related to the documentations. label Aug 24, 2017

jasnell added the meta Issues and PRs related to the general management of the project. label Aug 24, 2017

Trott requested changes Aug 24, 2017

View reviewed changes

cjihrig reviewed Aug 25, 2017

View reviewed changes

[Squash] Refine details based on feedback

101f84c

cjihrig approved these changes Aug 25, 2017

View reviewed changes

addaleax approved these changes Aug 25, 2017

View reviewed changes

jasnell mentioned this pull request Aug 25, 2017

perf_hooks: implementation of Performance Timing API #14680

Closed

4 tasks

lpinca approved these changes Aug 25, 2017

View reviewed changes

[Squash] Nit

41242d8

BridgeAR approved these changes Aug 25, 2017

View reviewed changes

Trott reviewed Aug 25, 2017

View reviewed changes

[Squash] Be forceful and assertive. Believe in yourself.

479aeae

Trott reviewed Aug 25, 2017

View reviewed changes

Trott approved these changes Aug 25, 2017

View reviewed changes

mcollina approved these changes Aug 25, 2017

View reviewed changes

[Squash] I think we're getting closer.

fbcd579

mcollina approved these changes Aug 25, 2017

View reviewed changes

[Squash] *Now* I think I've got it.

00df632

BridgeAR approved these changes Aug 25, 2017

View reviewed changes

Fishrock123 self-requested a review August 26, 2017 05:16

hiroppy approved these changes Aug 26, 2017

View reviewed changes

AndreasMadsen approved these changes Aug 26, 2017

View reviewed changes

jasnell closed this Aug 29, 2017

jkrems reviewed Aug 29, 2017

View reviewed changes

MylesBorins mentioned this pull request Sep 10, 2017

v8.5.0 proposal #15308

Merged

MylesBorins added the land-on-v6.x label Sep 20, 2017

MylesBorins mentioned this pull request Sep 20, 2017

v6.11.4 proposal #15506

Merged

meta: considerations for new core modules #15022

meta: considerations for new core modules #15022

Conversation

jasnell commented Aug 24, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Aug 25, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Trott left a comment

Choose a reason for hiding this comment

mcollina left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AndreasMadsen commented Aug 25, 2017

jasnell commented Aug 25, 2017

jasnell commented Aug 25, 2017

mcollina left a comment

Choose a reason for hiding this comment

AndreasMadsen left a comment

Choose a reason for hiding this comment

jasnell commented Aug 29, 2017

targos commented Aug 29, 2017

jasnell commented Aug 29, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment