Standard: Decide on version number for .NET Standard vNext

[terrajobst]

From the planning doc:

• Version number. In contrast to .NET Standard 2.0, which was a massive update in terms of APIs and the .NET Framework compatibility mode, this update seems relatively incremental. Also, the payload is comparable to .NET Core 2.1, hence .NET Standard 2.1 seems to make the most sense.
  
  
  
  • .NET Core and .NET Standard aren't the same thing. People will expect that the next version is 3.0 as that's what we called .NET Core. However, the API set is closer to 2.1 and argubly makes more sense within the context of the standard.
  
  

[jcapellman]

I think keeping it in line at 2.1 with .net core 2.1 will cut down on the confusion.

[clairernovotny]

What would the plan be for one based on .NET Core 3.0, .NET Standard 3.0? It is likely a reasonable assumption that UWP, Mono (and thus Xamarin) will add types from .NET Core 3, thus needing a revision.

[benaadams]

Depends timeframes for std and .NET Core 3.0 apis and if they would be a vNext+ standard or included in vNext standard.

e.g.

1. Skip 2.1, include minimal? set of Core 3.0 (most is NuGets?) release std around .NET Core 3.0
2. Do std 2.1 for now; and additional std 3.0 for .NET Core 3.0 timeframe

Might as well match .NET Core version numbers while the serendipity exisits

[terrajobst]

What would the plan be for one based on .NET Core 3.0, .NET Standard 3.0?

We decided to version the upcoming release of .NET Core as 3.0 because it adds a major set of APIs and scenarios, namely desktop development on Windows with WPF and WinForms, neither of which are applicable to .NET Standard. I expect some APIs from that time frame to be sensible for .NET Standard (e.g. any of the recent pull requests that will go in for .NET Core 3.0) but that will likely be a small-ish set so that the standard would rev from 2.1 to, say, 2.2.

In general, we should stop treating .NET Core and .NET Standard as somehow being related. The fact that most of the API candidates are originating from .NET Core is irrelevant. In principle they could come from any of the following .NET implementations and none of their version numbers are aligned with .NET Standard either. Said differently, .NET Core isn't special in any way. It's just yet another implementation of the .NET Standard.

[CShepartd]

.NET Core and .NET Standard should be separated at versioning the same as should be separated"platform specific" API from .Net Standard (only multi platform API should be supported)

[thomasclaudiushuber]

In general, we should stop treating .NET Core and .NET Standard as somehow being related

I think if you bring out .NET Standard 2.1, many developers will make a relation to .NET Core 2.1.

Did you ever think about ditching this whole major/minor versioning for .NET Standard and use an API level like Android does? If we would have started with that, the next version would be .NET Standard 9. Such a rolling version number makes it clear that there's no relation to any .NET platform.

| .NET Standard (old Versioning) | .NET Standard (new versioning) |
| --- | --- |
| 1.0 | 1 |
| 1.1 | 2 |
| 1.2 | 3 |
| 1.3 | 4 |
| 1.4 | 5 |
| 1.5 | 6 |
| 1.6 | 7 |
| 2.0 | 8 |
| vNext | 9 |

Today such a change might be confusing, as the new .NET Standard 7 (which is the old 1.6) would be smaller than the old 2.0.

To avoid this, we could start with rolling numbers with vNext, which means vNext is .NET Standard 3:

| .NET Standard (old versioning) | .NET Standard (new versioning) |
| --- | --- |
| 1.0 | 1.0 |
| 1.1 | 1.1 |
| 1.2 | 1.2 |
| 1.3 | 1.3 |
| 1.4 | 1.4 |
| 1.5 | 1,5 |
| 1.6 | 1.6 |
| 2.0 | 2.0 |
| vNext | 3.0, or better just 3 |
| vNextNext | 4 |
| vNextNextNext | 5 |

Is it really important to see that there's a huge difference between 1.6 and 2.0? At least not for me. It's more important to know which .NET Standard version can be used on which .NET platforms.
If the API surface of a new .NET Standard version is much bigger than the API surface of the previous .NET Standard version doesn't matter, as long as I can use my library on the required .NET platforms. That's the reason why I don't think it's important to express the size of the changes in a .NET Standard version with its version number.

Beside this fact, I think a rolling API level/.NET Standard version number would also make life much easier for you. You can focus on the APIs, and it's clear, bringing in new APIs means just version++.

Here for reference the API levels used by Android:
https://docs.microsoft.com/en-us/xamarin/android/app-fundamentals/android-api-levels?tabs=vswin

[thomasclaudiushuber]

I just read this here after my post above: https://github.com/terrajobst/standard/blob/511b206541d16f0c24c2ba746cb3abde311b1b98/docs/planning/netstandard-vnext/README.md#open-issues

There you already write

Or we could go with levels (10-16, 20, etc.)

Yes, I think levels are the way to go. What I don't like are the gaps in the levels.

[clairernovotny]

Agree levels make a lot of sense as there's already established precedent for it with Android and it helps differentiate the standard from .NET Core. With the version numbers being so close today, I think it's inevitable people will tie them together.

[CShepartd]

I think if you bring out .NET Standard 2.1, many developers will make a relation to .NET Core 2.1.

Lowering the level to the lowest intelectual power isn't good idea. We need to clearly see the future and have hope to ppl will know difference between .Net Standard and implementations like .Net Core/Framework/Other by writing good docs

[thomasclaudiushuber]

@onovotny Exactly, close version numbers will be tied together.

What would be if talk in the future about ".NET Standard levels" or ".NET Standard API levels" instead of ".NET Standard versions" and if we would apply the levels starting with 1?

Let's go with this table:

| .NET Standard version | .NET Standard level |
| --- | --- |
| 1.0 | 1 |
| 1.1 | 2 |
| 1.2 | 3 |
| 1.3 | 4 |
| 1.4 | 5 |
| 1.5 | 6 |
| 1.6 | 7 |
| 2.0 | 8 |
| vNext | 9 |

Wouldn't it be possible to use a TFM like this:

  <PropertyGroup>
    <TargetFramework>netstandardlevel3</TargetFramework>
  </PropertyGroup>

and the above code would be equivalent with this:

  <PropertyGroup>
    <TargetFramework>netstandard1.2</TargetFramework>
  </PropertyGroup>

And maybe if you're using the old TFMs, the compiler could give a warning that you should use the TFM netstandardlevel3 instead of netstandard1.2.

When you create a new .NET Standard library in Visual Studio, it would create this when the vNext .NET Standard is out:

  <PropertyGroup>
    <TargetFramework>netstandardlevel9</TargetFramework>
  </PropertyGroup>

[CShepartd]

some ppl dont understand difference between .Net Standard 2.0 and .Net Core 2.0
great idea! make one new thing: .Net Standard Level

I hope you are joking @thomasclaudiushuber with your posts

[thomasclaudiushuber]

I guess you know that your comic has nothing to do with this versioning issue. Today we have 8 .NET Standard versions, and with vNext we will have 9.

The topic of this issue is not like in your comic if there is going to be another version, because there will definitely be another version of .NET Standard. This issue is about what to call that next version, which is .NET Standard number 9. At least this is how I understood the title of this issue:

Decide on version number for .NET Standard vNext

But what should .NET Standard number 9 be: version 2.1, 3.0 or should the .NET team switch to levels?
And especially Why?

I brought in my thoughts. If you have arguments against levels or other arguments for new versions, bring them up here.

Just telling me or others things like

Some ppl dont understand difference between .Net Standard 2.0 and .Net Core 2.0

or

I hope you are joking

doesn't help anyone here. Tell the world why you think my idea is not good and bring up something that makes more sense from your point of view. This is how we can move forward and have a good discussion here.

Thanks,
Thomas

[clairernovotny]

@thomasclaudiushuber I don't think we need to introduce a new concept or TFM. We can't use existing numbers because they'd conflict and I don't see a huge amount of value in renumbering old versions (whose usage is in decline).

I'd probably jump directly to netstandard3 instead of 2.1 and then nothing breaks (or needs to change on the nuget side either).

[thomasclaudiushuber]

@onovotny Yep, true, good arguments to keep the old stuff just as is.

Jumping directly to netstandard3 sounds good to me. And from there on the version number could be incremented by 1 with every new .NET Standard version. Then we would have something like a level from there on.

The question is then if it is just .NET Standard 3 or .NET Standard 3.0. I would go for just 3 to make it clear that from here on a rolling number is used. A future like this looks good to me:

[bartonjs]

I'd stick with semver as the guide. If a release is mainly about adding new methods to existing types, that's a minor version that Mono/Xamarin/Unity should be able to roll in in the next(-ish) update.

Major versions would indicate either "a breaking change has happened" (which, IIRC, was the original reason for "2.0" over "1.7", then we backfilled all the breaks) or "something different and expensive is in this". Since this is the first version with prolific ref-like-structs (Span), that might qualify as "major".

That said, if we want to pre-break the coupling from .NET Core's anticipated 3.0, nothing stops .NET Standard from jumping ahead to 4.0, or even 2018.0 (the year of the major change decision being the major version, the minor version incrementing as needed). If 2018 is too big, then 16.0 (since it's currently 16 _anno punctum rēte compage_).

[CShepartd]

@thomasclaudiushuber By my ealier post I wanted to show absurde of your idea. You want rebuild and add additional useless stuff to well designed thing like current .Net Standard. Do you remember PCL Profile mess? Don't make it again with your .NET Standard levels/.NET Standard API levels. Do not take it personally, it is just very bad idea

.NET Core and .NET Standard aren't the same thing and ppl need to understand that. We shound't change everything only because someone can't read with understand what is .NET Standard. .NET Standard team need to do their job without watching at any other. Syncing .Net Standard 2.0 with .Net Core 2.0 was bad idea and this need to be broken.

BTW Interesting thing to read when you want start think about versioning https://blog.golang.org/versioning-proposal
https://github.com/golang/proposal/blob/master/design/24301-versioned-go.md

[clairernovotny]

@bartonjs As I understand it, from an API surface area perspective, there will never be breaking changes -- it's all cumulative. So there'd never be a need to distinguish major/minor in this context.

That's not necessarily true of the runtime. NET Core 3 may change behavior that was in 2.

[bartonjs]

As I understand it, from an API surface area perspective, there will never be breaking changes -- it's all cumulative.

While this is what I expect in practice, I still hold out hope that one day we'll start to remove things that have been [Obsolete] for over a decade. (Nothing would stop individual implementations from still offering it, but the requirement to have that method or type name there would be gone).

[CShepartd]

As I understand it, from an API surface area perspective, there will never be breaking changes -- it's all cumulative.

Like @bartonjs mentioned it can be not cumulative. For example version 3 can change everything (all API). There is no rule for it. Rule is to publish API

[thomasclaudiushuber]

I think it's not as simple. There are different perspectives for obsolete things and a cumulative .NET Standard, like these:

Library Dev
The fact that .NET Standard is cumulative is a big advantage from a library developer point of view.
Because it allows me to write a library today that targets for example .NET Standard 1.3, and then I can be sure that my library can be used on any .NET platform that implements .NET Standard 1.3 or higher. My library can be used in the future on new .NET platform versions without re-compilation. That's why I think cumulative is important from a library developer point of view.

Non-cumulative would still allow me to build one library for different platforms, but it's not guaranteed that my library will work on future versions of different .NET platforms. Maybe next year a new version of a .NET platform won't implement my old .NET Standard anymore. Hm.... things get by far more complex than today when this happens.

.NET platform
From an implementing platform point of view cumulative means that you have to carry around all the obsolete stuff to support the Standard, and maybe you just throw PlatformNotSupported Exceptions. Here a cleanup would be great, especially for new .NET platforms that don't have the existing APIs yet. But how likely is it that there will be another .NET platform implementing the .NET Standard? The existing platforms have those APIs defined in .NET Standard 2.0 already.

Spec
From a Specification point of view it means that you have things in your spec that shouldn't be there anymore. There's a reason why things are obsolete. And from this point of view it makes most sense to clean the spec up. But what would you gain with it? The advantage would be again for new .NET platforms, they don't have to implement that stuff. But then they only support the standard from that new version on. So they might anyway implement the obsolete stuff to support the older .NET Standard versions and so more libraries.

[terrajobst]

@thomasclaudiushuber

Yes, levels did occur to me and it's called out in the planning doc. The problem I see with this is:

• The entire infrastructure we use is based on version numbers. Now, we could just "map" versions to levels by removing the period, so we could have 10, 11, 12, 13, 14, 15, 16, 20, and 21. It's unclear how leaky this is in tooling though. In the end, the only thing that would change is how we display .NET Standard versions in the UI or the CLI.

• We want to be able to "insert" versions if necessary. Say we need to create a new standard between to released versions (e.g. to model a set of platforms we care about that can only provide partial support for the latest version). If we use int-based levels it might be hard to insert unless we plan accordingly using some padding.

• Levels are a new concept. I'm undecided if introducing a new concept will cause less confusion or more confusion. People already complain about our stuff being complicated. A good example is this comment.

[terrajobst]

@onovotny

I'd probably jump directly to netstandard3 instead of 2.1 and then nothing breaks (or needs to change on the nuget side either).

Maybe I missed it but what would be the benefit of jumping to 3.0 (besides aligning with .NET Core 3.0, which I actually think is a bad idea)?

[thomasclaudiushuber]

@terrajobst

Levels are a new concept. I'm undecided if introducing a new concept will cause less confusion

I think levels like this 10, 11, 12, 13, 14, 15, 16, 20, and 21 will cause more confusion, especially to people that are new to .NET Standard. In a level I would expect no gaps and I would expect that it starts from 1. A gap like 16 to 20 looks weird in a level, while a version gap from 1.6 to 2.0 is fine.

I'm also not totally sure if leveling brings less confusion. To me and maybe to those of us with Android experience who are used to levels, levels sound like a valid concept. But from a pure .NET perspective, we have version numbers everywhere and no levels. Which could be a good and valid reason to stick with version numbers and decide against leveling.

We want to be able to "insert" versions if necessary

Ok, that's definitely a good and hard argument against levels. And a good reason to stick with version numbers.

[thomasclaudiushuber]

@terrajobst @onovotny

As far as I understand the docs, .NET Standard vNext is implemented by .NET Core 3.0, but not by .NET Core 2.1 and 2.2, am I right?

• I think announcing .NET Core 3.0 and .NET Standard 2.1 would be totally fine. Because then .NET Core 2.1 is a bit older and not in the spotlight anymore, so the .NET Standard 2.1 version is not really confusing.

• Announcing for example .NET Core 2.2 that implements the new .NET Standard 2.1 might be confusing, as .NET Core 2.1 is still too present and people still do that relation between Core and Standard. But what would be the alternative? .NET Standard 2.2? That would even strengthen the association between .NET Core and .NET Standard, which I think is bad.

In both cases mentioned above, .NET Standard 2.1 might be the best option. And that's also what the planning doc suggests. The more I think about it, the more I think 2.1 is the correct way.

Why .NET Standard 2.1 makes sense

Using the version of a single implementation (.NET Core) as an argument for the next version of the specification (.NET Standard) is wrong. We all know this. And from this point of view, taking into account the API set, 2.1 is the only right option for .NET Standard vNext, no matter when it is announced and which platform versions implement it.

[KristianWedberg]

SemVer obviously has a _huge_ mindshare, and we can minimize confusion by explicitly following it.

So, given that:

• .NET Standard 2.0 is set in stone
• 'All' future .Net Standard versions are expected to be backwards compatible
• We want the ability to "insert" versions if necessary

I suggest that:

• Future versions are named 2.1, 2.2, 2.3, ... ad infinitum
• The Major number never changes
• The Minor number becomes the 'level', incrementing monotonically
• The Patch number is only used in the rare case of inserting a version, starting at "5", e.g. 2.1.5, to allow inserting additional 2.1 versions both before and after

Additionally, if policy is changed and breaking changes _are_ introduced five years from now, _then_ the Major number would increment. The Minor number could either restart from "0" or keep incrementing as a level, I prefer the latter.

Thoughts?

[CShepartd]

As far as I understand the docs, .NET Standard vNext is implemented by .NET Core 3.0, but not by .NET Core 2.1 and 2.2, am I right?

Please stop connecting .Net Standard with .Net Core. .Net Standard only provide API layer without implementation (interfaces). It can be implemented in any kind of framework. Do you understand? Why ppl care so much about connet that unconnected things. Direction is Interfaces > Implementation, not Implementation > Interfaces

My suggestion is .Net Standard Major.Minor.Patch:

Major version | Minor version | Patch version
------------ | ------------- | -------------
Increment for backwards incompatible changes | Increment for new features (cumulative) | Increment for bug fixes

Semantic Versioning docs: https://semver.org/

[thomasclaudiushuber]

Do you understand?

I'm assuming everybody in this discussion knows that .NET Standard is a specification that defines an API Set for the different .NET platforms.

But to be honest, I don't know what's your problem with my question where I'm asking which version of .NET Core will implement the next version of .NET Standard. As you might know, .NET Standard 2.0 is for example not implemented by .NET Core 1.0. So, when you build a .NET Standard library, it's quite important to know which platforms implement the targeted version.

Of course the direction is interface to implementation. Nobody said anything else.

We talk here about the version, not what .NET Standard is. I think everybody here knows what it is. And as mentioned, bringing out a .NET Standard 2.1 with .NET Core 2.2 might cause confusion. But as I said, version 2.1 might be the best option for vNext.

[CShepartd]

But to be honest, I don't know what's your problem with my question where I'm asking which version of .NET Core will implement the next version of .NET Standard.

If you know proper direction (Interfaces > Implementation) then you shoud know where to ask (yes, go ask.Net Core team when they will implement .Net Standard). Do you now see where i have a problem?

[thomasclaudiushuber]

Yes, I see, your problem is that you don't know that there's a review board for .NET Standard, and that the members from implementing platforms are in that board.

Take a look here: https://github.com/dotnet/standard/blob/master/docs/governance/board.md. As the starter of this issue, @terrajobst , represents the .NET Platform, I think it's more than ok to ask this question about .NET Core here, as it was related to the versioning thoughts I had.

But instead of just asking me "Why don't you ask this the .NET Core team" you prefer to write that I don't understand the difference between an interface and an implementation, and that you have a problem that I'm asking a question here.

To be honest, your behavior sucks. I can live with that. But if you write in that style to younger developers, they won't participate here anymore. Is this your intention, is this what you want? You should think a bit much more about how you treat others.

[CShepartd]

By your logic:

If people here eating bread sometimes then can i ask here about which flavor of bread is best?

No. Be specific. Ask question in accurate place, not where are you actual standing. You are making a mess from this issue.

[clairernovotny]

@terrajobst

Maybe I missed it but what would be the benefit of jumping to 3.0 (besides aligning with .NET Core 3.0, which I actually think is a bad idea)?

The reason is to be more like levels, using an integer. Though I'm thinking 1...1.6, 2, 3, 4, not 10, 11, 12... 20, 30.

To me, that helps decouple the idea that the standard is tied to the .NET Core release. It also gives you room to add in partial versions. If this is .NET Standard 3, then something between .NET Standard 2 and 3 could still be 2.x.

Nothing breaks and the TFM's/NuGet doesn't need to change at all.

[whoisj]

Now, we could just "map" versions to levels by removing the period, so we could have 10, 11, 12, 13, 14, 15, 16, 20, and 21.

This doesn't account for the situation where we hit v{major}.10. For example, if we ever need to release a v2.10 how would a pure leveling design account for that? The major version is supposed to promise compatibility for consumers of the same major version number.

[terrajobst]

@onovotny @whoisj @thomasclaudiushuber

[Levels]

I think if we do levels, they relatioship between a level and the version number needs to be an (ideally bijective) function, i.e. something we can compute. Having a mapping table is problematic as we'd have to carry that information into all the tools that we'd ask to make decisions. I'm scared that there is a long tail of bugs and fragility we introduce for what amounts to a cosmetic change. As you pointed out, there are practical problems with having a function projecting versions to levels which kind of kills that for me.

Now, I could be convinced that this is purely a UI change for the drop down in VS but then I'm concerned about this becoming leaky so that developers forever have now to understand both, levels, and versions. And that kinda kills that too.

[terrajobst]

@bartonjs

While this is what I expect in practice, I still hold out hope that one day we'll start to remove things that have been [Obsolete] for over a decade.

I'll push back on any proposals to do that. Now, that doesn't mean I'll win that argument though, so there is a chance this still happens. So from an engineering standpoint I do find it reasonable to say we need to have a versioning strategy that allows us to somehow represent that information should it become necessary. I don't consider that over engineering or a case of YAGNI; I believe this is part of the due diligence and conservative design process responsible owners of widely used technologies have to do.

[terrajobst]

@thomasclaudiushuber @KristianWedberg

[SemVer]

Also, I do think we'll likely want to bump the major version for another reason, specifically to convey that the upgrade is huge. In this context, "huge" is another way of saying "impactful", which is neutral w.r.t whether it's a positive set of changes (large numbers of APIs being added) or negative (will take a while for all .NET implementations to catch up or that it has breaking changes). That's the reason why .NET Standard 2.0 wasn't .NET Standard 1.7.

People often seem to think that SemVer disallows bumping the major version if there are no breaking changes. That's not actually true. All SemVers says is that if there are breaking changes, you must bump the major version, which I'm more than OK with. But it doesn't mean that we can't ship a fully backwards compatible .NET Standard 3.0.

The reason I believe .NET Standard 2.x is a better version choice for vNext is:

• It's largely just minor incremental changes
• Yes, Span<T> is a super cool feature, but it's not nearly as big as many other changes we've done before (Generics, LINQ, Async etc), so I'd hold my horses ;-)
• The delta between 1.6 and 2.0 is much larger than between 2.0 and vNext. I'm afraid by labelling it as 3.0 we somehow make it more attractive than it should be. Most libraries should probably continue to stay on 2.0 (because they don't need 2.1).

[terrajobst]

@CShepartd

You make some compelling points but please refrain from using such a combative approach. I've hidden some of your comments because they are just accusatory/off-topic. Don't attack the person, attack their ideas. And by attacking I really mean: address their strongest point with a great counter argument. If your behavior doesn't change, I'll eventually ban your account as it makes it harder for us to have a constructive discussion on a topic which isn't exactly trivial. I don't want to waste time by getting this conversation derailed due to inflammatory comments.

[KristianWedberg]

@terrajobst

The downside of making Major increments _sometimes_ mean "a huge but backward compatible change" is that that leaves no clear way to signal an _incompatible_ upgrade.

I.e. a future 3.0 backward _compatible_ release looks the same as a future 4.0 backward _incompatible_ release - is it a low risk upgrade, or do I need to check and test very carefully?

Why not simply say "from now on we do SemVer version numbering, where a fixed Major means the changes are backward compatible, etc."? This seems a lot more useful than being able to signal a "huge" release.

Except from a marketing perspective. Or did I just answer my own question? :D

[terrajobst]

Marketing often has negative connotations but I think it applies here, from a technological choice. How we increment the version controls how people perceive the significance of the release. As I wrote above:

The delta between 1.6 and 2.0 is much larger than between 2.0 and vNext. I'm afraid by labelling it as 3.0 we somehow make it more attractive than it should be. Most libraries should probably continue to stay on 2.0 (because they don't need 2.1).

[IanKemp]

Changing the versioning scheme for a point release is just a bad idea all around. Ship .NET Standard vNext as 2.1 now, continue with SemVer for any other point releases, have the SemVer-vs-API-levels argument properly when 3.0 is on the horizon.

The "API levels will make it more difficult to confuse Core and Standard" argument doesn't fly for me, for the simple reason that these two are already pretty much synonymous in many developers' minds. To properly differentiate the two will require one or both to be completely renamed, and this far down the line that ain't gonna happen.

[thomasclaudiushuber]

@KristianWedberg

Your idea is good, but I see the point @terrajobst mentions:

How we increment the version controls how people perceive the significance of the release

Most .NET developers I know - including me - don't think about versioning in that way you describe it above, where the major version only changes on breaking changes.

If I would read that .NET Standard vNext is .NET Standard 3.0, the first thing I would think is "wow, again a huge release with a lot of new stuff in it", and not "Oh, a new release with breaking changes".

I could live with .NET Standard 3 if we would use a leveling approach, but there were some strong arguments in this discussion that leveling is not a good idea at all.

So, for me .NET Standard 2.1 is the way to go for vNext. And if a lot of new stuff comes in a future version or if there are breaking changes, then an increase of the major version like it was done with .NET Standard 2.0 is good.

But anyway, if there are no breaking changes in .NET Standard vNext, the next version would be .NET Standard 2.1, also with your approach.

[KristianWedberg]

@terrajobst @thomasclaudiushuber

For me it comes down to:

• How much confusion has the current version number approach resulted in?
  
  
  
  • (I think it's a lot, especially vs. .NET Core/.NET Framework version numbers)
  
  
• How much clearer, less confusing, and generally useful for the target audience would it be to
  say "Net Standard now follows SemVer" vs. "Net Standard version numbers depends on the
  size of the change"?
  
  
  
  • (I think a lot better, and very little explaining needed since SemVer is both well known
    
    and well respected. It tells us not only what the current version number is, but also provides
    
    a clear policy for how future numbers will change.)
  
  
• How much value is there marketing wise to be able to differentiate between smaller
  and larger revisions?
  
  
  
  • (I have no idea, possibly significant value)
  
  
• If doing SemVer, how should large/small releases be differentiated and communicated?
  
  
  
  • (I suggest picking two marketing tags to label each release, e.g. Maxi/Mini. Pick any tags _except_ Major/Minor.)
  
  

Weigh them up and make a decision. And publish the numbering policy. "2.1 and SemVer going forward" is a lot more useful than just "2.1".

[thomasclaudiushuber]

Yep, good points. But I'm not sure about this one:

very little explaining needed since SemVer is both well known and well respected

[CShepartd]

@terrajobst

Don't attack the person, attack their ideas. And by attacking I really mean: address their strongest point with a great counter argument.

That is what Im doing. I never said "he is idiot" or any other argumentum ad personam. He is representing ideas what I "attacked" by your definition - by the logic, showing weakest points. I saw your fight against "trolls" on others issues in others project (for example https://github.com/dotnet/csharplang/issues/1718 or https://github.com/dotnet/csharplang/issues/1696) but here you are going so far and so fatst, attacking personally me (oh irony). You even hidden my idea about semantic versioning (this comment with tables, even can not link to it cuz its hidden). I think you did here wrong job hidding my posts and trying to scare me of ban without any reasons when my posts was eristic correct

[jnm2]

@CShepartd

Among other (barely understandable) things you wrote, you said, "You are making a mess from this issue." That is accusatory and personal.

[CShepartd]

@jnm2 Because he did mess by asking there when .Net Core will support next .Net Standard. Is this place designed for that questions? I dont think so. Ok, we are doing a mess too by our semi-private dialog, so let focus on issue (and let rethink @terrajobst about his action with me).

[jnm2]

Even if it was true, the tone of your statement is unacceptable.

[terrajobst]

@CShepartd

Sorry, but we're spending too much time in this issue debating your conversational style. I've blocked your account for now. Please ping me under [email protected] to see what we can do about that.

[terrajobst]

To make this discussion actionable, I propose we don't consider changing the versioning scheme here and stick to deciding version number. If someone wants to change the versioning scheme, please file a separate issue.

From what I've heard this leaves us basically with two version numbers:

• 2.1
• 3.0

I'm leaning towards 2.1. Others?

[benaadams]

2.1 👍👎

[benaadams]

3.0 👍👎

[terrajobst]

@benaadams

You're da man! Great idea 😄

[bartonjs]

2.5 :+1::-1:

[terrajobst]

Can you provide a rationale for that version number? (I think I know why, but for the benefit of people voting)

[bartonjs]

Can you provide a rationale for that version number?

Well, to quote you from https://github.com/dotnet/standard/issues/833#issuecomment-406124954

We want to be able to "insert" versions if necessary. Say we need to create a new standard between to released versions (e.g. to model a set of platforms we care about that can only provide partial support for the latest version). If we use int-based levels it might be hard to insert unless we plan accordingly using some padding.

It also has the advantage of not being a version of .NET Core.

I can also throw out my 2018 and 16 versions, but I don't expect they'd be very popular :smile:.

[Code-DJ]

@bartonjs I like the idea of 2.5 but long-term will it be sustainable? I guess if there is a need for Standard vNext around the time of .net core 3.5 (if there is one), we will have to fall back to .NET Standard 3.1 or 3.6 or 4.0 just to avoid 3.5. I guess there is no good answer here.

[robmen]

@terrajobst What is the trigger for a new .NET Standard to be published? It seems like it is a fairly momentous occasion. If so, then I would argue every time a new .NET Standard is triggered, it should be a major version. If there are retroactive/"bug fix" .NET Standards those would be a minor version (against appropriate major version).

If the above doesn't make sense, it would help me understand the reasoning a lot if there were examples that clearly delineated major updates (Span<T> would seem like an easy example but it was used as a counter-example, so I was confused).

[terrajobst]

What is the trigger for a new .NET Standard to be published?

That's a good question and I don't think there is a good answer besides "if enough new features are available to make a release". We don't want the standard fall behind too much. The reason to update is to push more APIs across all implementations to allow sharing.

If there are retroactive/"bug fix" .NET Standards those would be a minor version (against appropriate major version).

There isn't a good scenario for a bug fix in API surface. Logically, .NET Standard is the same as a targeting pack. And historically the version number was decided on a combination of several factors.

For .NET Standard I've tried to outline our principles in the governance documentation:

The version number is subject to discussion and is generally a function of how significant the new version is. While we aren't planning on making breaking changes, we'll rev the major version if the new version adds large chunks of APIs or has sizable changes in the overall developer experience.

Of course, what constitutes as a sizable change is in the eye of the beholder.

[Happypig375]

@terrajobst

"if enough new features are available to make a release"

If one single cryptography algorithm can constitute a .NET Standard (1.4), then what would be holding back a new version of .NET Standard?

[terrajobst]

The .NET Standard 1.x versions were generated and all shipped at the same time. Shipping five versions or six versions makes no difference there. But moving forward, spinning a new release requires shipping a bunch of changes across a variety of products and isn't cheap. We wouldn't do this for a single type.

[MV10]

I wound up here when I found myself wondering whether .NET Standard has a published roadmap. Coincidentally, I've recently spent a lot of time explaining .NET Standard and .NET Core to experienced but sheltered enterprise devs and related management, most of whom literally haven't realized anything has changed in the .NET world.

I'm teaching folks who haven't even _heard_ of .NET Standard, so I've seen the confusion up close, and I think it's more about the initial understanding of what has happened in the .NET world rather than anything relating to version numbers. Similar version numbers probably contributes to that _initial_ confusion, but my experience is that as soon as they grasp ".NET Standard = API spec" it's trivial to clarify that the version numbers are unrelated. (Why Standard wasn't named ".NET API" is beyond me, but that horse has left the barn.)

There have been several great observations about why semver is attractive with major increments indicating "lots of new stuff" (and not necessarily indicative of breaking changes). I know I'm just one guy among millions, but this is certainly how I have been thinking about the versioning since 2.0 released. It's what I was expecting if/when there is a 3.0 and it's actually how I've been explaining it to those new to Standard/Core.

From the standpoint of a user of Standard/Core, I've been working with Core since the 1.0 RCs and on a day-to-day basis, out there in the trenches getting production work done, it's certainly easier to remember "2.0 was that big API expansion." Sure it's probably difficult to decide what exactly qualifies, but as a library author, which is where this matters most and the guidance is to target the lowest-versioned spec possible, it "feels safe" to decide to target major releases like 2.0 or 3.0, knowing you only need to dig into the point-release details if your library needs to support some specific minor new addition to the spec.

Versioning in lockstep with .NET Core versions seems like the most confusing option. It reminds me of the early days of .NET when it wasn't always clear whether or how .NET Framework and ASP.NET versions were related. I think someone already pointed out that also lends undue importance to .NET Core as the "real" .NET rather than "just an implementation."

In short, I don't think semver or a slower rate of versioning is as confusing in the real world as many here seem to fear. That concern might be magnified within this group because MS didn't really paint a clear picture of what was going on when Standard/Core were brand new, but those days are far behind us.

I realize mostly I'm summarizing what has already been said, but I thought I'd add my two cents from the perspective of spending months of dealing with the new-to-Core learning-curve over and over again. (My apologies if anyone was emailed with a confusing, partially-edited version of this response, the "submit" button misfired!)

[terrajobst]

We have decided to use version 2.1. The reason was outlined in #858.