Detail governance model for .NET Standard

[terrajobst]

This updates the previously fairly vague definition of the .NET Standard review board and outlines the process by which we decide whether APIs will be added to .NET Standard. Key aspects:

• Anybody can submit API standardization requests
• The API request needs a sponsor that is on the .NET Standard review board
• The API needs an implementation in at least one .NET implementation
• The .NET Standard review board has representatives from all existing .NET implementations. @migueldeicaza will act as the chairman, which is fancy way to say he'll act as the tie-breaker.

@migueldeicaza @dotnet/fxdc @dotnet/nsboard

[karelz]

Do we plan to publish list of reps for each platform?

[terrajobst]

We probably should have a public GitHub team "board" with the representatives. I'm not sure that having a list with spelled out names like in the .NET Foundation is key though. Especially because the people might change.

[karelz]

Who decides on sponsorship? Is it round-robin? Does each requester have to have negotiated ACK from one of the board members?

[terrajobst]

To me, sponsorship implies that the sponsor decides whether they want to sponsor the proposal. If you submit a proposal that nobody wants to sponsor, your proposal is effectively already rejected.

[karelz]

OK, that is not IMO clear, we should clarify it.
Also, how is an external person supposed to find a sponsoring board member? Will board members review incoming on regular basis?

[terrajobst]

OK, that is not IMO clear, we should clarify it.

Yep, will do.

Also, how is an external person supposed to find a sponsoring board member? Will board members review incoming on regular basis?

I'd say that's part of the planning process for each release. We look at all filed issues and triage. Everything that doesn't have a sponsor will be rejected and closed.

[karelz]

Is it ok to file issues of the size of single API? (e.g. Dictionary<U,V>.GetValueOrDefault)

[terrajobst]

Probably not. I'm thinking that we should have a process where any members introduced by any .NET implementation are automatically considered for the next iteration of the .NET Standard. They might still be rejected, but it seems divergence in those is generally not desired so tracking them individually is just noise and prone to errors. I'll call it out.

[karelz]

I see. Then we should have a process/way for dispute to our initial decisions (rejections). I bet people will be wondering "why is not my favorite API part of .NET Standard, I really need it there" - that would bring it to the board attention again ...

[benaadams]

I'm thinking that we should have a process where any members introduced by any .NET implementation are automatically considered for the next iteration of the .NET Standard.

Aww, I was going to automate opening an individual issue for each method or type in https://github.com/dotnet/core/blob/master/release-notes/2.1/api-diff/2.0-vs-2.1.md 😉

[terrajobst]

@benaadams I don't know who you are. I don't know what you want. But if you're looking for creating noise in my repo, I assure you I don't accept that. Over the years, I've picked up a very particular set of skills. And those skills make me a nightmare for people like you. If you now promise to not automate filing issues, I will just walk away and that is the end of it. But if you don't, I will come for you. And I will find you. And when I do, I'll install Java on all your machines.

[karelz]

Does a specific license matter? (e.g. GPL is not quite reusable with MIT)

[terrajobst]

Good point. Will call out that the license needs to be compatible with MIT.

[jbogard]

What constitutes "all" .NET implementations? Windows 8.x, Windows Phone, and Windows Phone Silverlight were dropped. Is it only .NET implementations that have current LTS?

Say Everyone But .NET Framework can implement some new API, does full .NET get left behind?

[terrajobst]

This only covers implementations that are still evolved. If a platform is done, that naturally means it will no longer implement later versions of the .NET Standard spec either, so the standard no longer has to consider them either.

[danmoseley]

You didn't list the API review board signoff. I assumed the .NET Standard request would be downstream of approving the final API shape. Running those processes potentially in parallel could make things quite complicated especially if the review board suggests changes.

I am not sure how much precedent we have for API review of API's whose initial implementation is not in .NET Framework or .NET Core. That seems like something we can fix, though.

[danmoseley]

Particularly since you suggest that additions must be mature API's. That seems to imply that they've been okayed by API review.

[terrajobst]

Good point. I've changed the wording above to demand stable APIs as input, as opposed to net-new- or prototypical APIs. I don't want the review board to become another API design review -- the intent is that the board only has to decide whether the API should be in the standard.

[danmoseley]

You've mentioned that some future API's could appear first in Mono, as opposed to appearing first in .NET Core which seems to almost invariably be the case right now (I think). Is the API review board set up for that? ie., do we have precedent for Xamarin folk presenting API to it, and being fully part of decision making there?

[stephentoub]

Also (and I expect this would be super rare), what happens if different platforms independently add conflicting APIs?

[danmoseley]

What about calling out exchange types? Since those often can't easily go in libraries either.

[terrajobst]

Added

[jnm2]

I know popular usage is beginning to blur the line now, but I would suggest “the board comprises representatives.”

[jnm2]

copy → copies
“from .NET Framework & .NET Core base class library” → “from the .NET Framework & .NET Core base class libraries” ❔

[jnm2]

shepard → shepherd

[jnm2]

“needs” → “needs to be”

[jnm2]

modification → modifications, it's → they're
(to agree with the plurals ‘fixes,’ ‘improvements,’ etc.)

[jnm2]

Ubiqutous → Ubiquitous

[khellang]

Easier or either?

[terrajobst]

Gee. I'm so bad at writing. Now you see what @mairaw has to endure here :-)

[jnm2]

I may find typos hard to overlook most of the time, but that doesn't stop me from creating them myself at a frightening rate...

[davidfowl]

I think we need to forbid this until the “board agrees”. We can’t have types in the standard diverge differently as they make their way to the standard.

[terrajobst]

Not sure I understand. Are you proposing that every time we add a member to a type that is in the standard — in any implementation — the board has to agree? That isn’t a time efficient way to drive the platform.

I feel like the risk is extremely low:

1. It’s extremely unlikely that we’ll have to reject members.
2. And even if we do, nothing bad happens. It’s a wart, but assuming there are few cases, it’s not a substantial issue.

[davidfowl]

I'm saying it can't just be considered then it has to just be "in".

[terrajobst]

I think that is the default position.

[dasMulli]

This would mean that all the span-based APIs on existing types are now automatically up for consideration.

[weshaggard]

This would mean that all the span-based APIs on existing types are now automatically up for consideration.

Yes they are.

I agree we don't want to block new API additions on existing types in a given .NET implementation as that would slow things down too much. However it is worth mentioning that if there are new APIs going in that might have issues that folks want feedback on they can take them through our API review process that we have setup http://aka.ms/apireview. While not a requirement it is a highly recommended for these type of APIs and probably worth mentioning in this doc.

[weshaggard]

I was expecting you to say something about any such libraries APIs not needing to be included in the standard itself.

[weshaggard]

Of course one exception to this is IL that ships in one of the platforms.

[benaadams]

Worth mentioning something about type forwarding?

[terrajobst]

@weshaggard

I was expecting you to say something about any such libraries APIs not needing to be included in the standard itself.

That's basically what the section was about. I've slightly changed the wording to hopefully make that more clear.

Of course one exception to this is IL that ships in one of the platforms.

Right, which is why I wrote:

If an API ships as a library, it's much harder for any .NET implementation to use the types as part of their implementation or public API surface. Hence, there is a lot of value in adding widely used concepts to the .NET Standard in order to use them throughout all .NET implementations.

[weshaggard]

I think it might be worth calling out some counter examples of APIs that we wouldn't include. Things for new technologies that are not yet industry standards.

[terrajobst]

I thought we covered this under "mature APIs".

[weshaggard]

Partially. I still think there could be debate about whether or not an API is mature vs a Technology is mature. I'm OK either way.

[terrajobst]

That's fair. To me, it's hard to envision a world where the API is mature but the tech isn't though. The closes thing I can think of app model like technologies (like DI containers or OR mappers) which seem to be subject to fashion and patterns which don't tend to last for very long. I don't know how to phrase that though. Maybe a new bullet point like this:

Fundamental. The standard is about foundational technologies. We want to avoid adding concepts that are often subject to changes, such as DI containers or OR mappers.

[bartonjs]

Wouldn't, generally, something like DI or OR be "on" netstandard vs "in" netstandard?

[weshaggard]

Asside: While I know you are trying to call out what should be in the standard or not. I think labeling and calling out the difference between "on" and "in" would be a big help and I can also have a place to point folks at whenever I have to explain that concept.

[terrajobst]

Alright, I've added section before and discussed the "on" vs "in" a lot more. Let me know if this helps.

[stephentoub]

By "everywhere" here, I assume this means "all .NET implementations" rather than "all OSes". There are / will be APIs that are in all .NET implementations but that don't run everywhere.

[terrajobst]

That's fair, I'll clarify.

[loic-sharma]

We'll track features, no individual APIs

Should be:

We'll track features, not individual APIs

[adamralph]

Generally LGTM.

[adamralph]

What are "grab-bag releases"?

[terrajobst]

Grab-bag releases are where you've got a large number of small-ish things that don't follow a set of scenarios. That makes it hard to prioritize and make trade-off decisions.

[adamralph]

👍 thanks. I'm not sure the term "grab-bag" is recognised outside North America.

[terrajobst]

How about "potpourri"-style releases?

[terrajobst]

Reworded to:

.NET Standard updates are planned and will generally follow a set of themes. We avoid releases with a large number of tiny features that aren't part of a common set of scenarions (we call them "grab-bag-style releases"). Instead, we try to define a set of goals that describe what kind of feature areas a particular .NET Standard version provides. This simplifies answering the question which .NET Standard a given library should depend on. It also makes it easier for .NET implementations to decide whether it's worth implementing a higher version of .NET Standard.

[adamralph]

Why is it much harder?

[terrajobst]

There is no single line answer but let me try with an example: immutable collections.

Right now, it's not part of .NET Standard but a NuGet package that sits on top. This means APIs in .NET Standard cannot return, say, ImmutableArray<T>. The shared framework in .NET Core includes immutable collections due to implementation dependencies. However, the shared framework allows consumers to load a later version of the package if they choose to do so. This means it's largely transparent for application authors and the illusion is that immutable collections remains out-of-band. But we need to be careful how we layer our dependencies and this prevents us from doing some things entirely (such as using ImmutableArray<T> at the bottom of the stack). Strictly speaking it's not impossible to keep BCL-ish APIs out of the standard, but it can become costly/hard to make these types work in the implementations while retaining their out-of-band character.

[adamralph]

This sentence is very difficult to understand.

[terrajobst]

Rephrased to:

Please note that universal doesn't necessarily mean literally everywhere. If that were the bar, we'd end up penalizing the common cases by excluding a concept just because there are some rare cases where this concept doesn't work or doesn't apply.

[benaadams]

in at least one .NET implementation

Been thinking about this and discussing it... The timing of what goes into a standard is obviously important, as you want the waves to be "implementable" prior to the next standard and the standards are always additive.

So only one implementation may be problematic as you may have an implementation that has all the features from x.4 but is missing features from x.3 so it can't implement x.3 or x.4 or any later standard (until it has the x.3 features) so prehaps the web browser standardization process should be followed?

i.e. in at least two .NET implementations

Don't make an abstraction if you are only going to have one implementation? When you get more than one, then make an abstraction...

[terrajobst]

I've thought about this a lot too. But how would you drive the second implementation? In other words, what's the process by which we'd communication which API surface we'd want another party to implement? It seems to me the deliverable and process would be close to, if not virtually identical, to the work in proposing the standard. So if the goal is agility, it might be better to just focus on proposing the next version of the standard and get all parties to implement it at once.

Of course, there are cases where the API can just be implemented by grabbing an implementation from CoreFx and copy & pasting the source code into the other code base which some cases happens in parallel with the development (e.g. Mono continually picks up code from CoreFx). So in practice it might not make difference either way.

[akoeplinger]

URL contains typo: mareksafar vs. marek-safar

[akoeplinger]

typo: sign-of

[svick]

Is this really meant to be "poor consumers"?

[terrajobst]

I meant "pure consumers" but apparently

[terrajobst]

Thanks for all the feedback. I believe to have addressed it all, so I'm going to merge this unless I hear back in an hour or so.