Roslyn: NuGet Release Notes

[dmitry-shechtman]

I looked really hard to see what's new in Microsoft.Net.Compilers.1.1.0, but to no avail.

The .nupkg release notes read:

Preview of Microsoft .NET Compiler Platform (Roslyn)

Am I in the wrong place?

Thanks

[mteper]

:+1:
Went looking for release notes for 1.2.1 and came up empty.

[jmarolf]

We should publish some notes.

To get started, all of these bugs were fixed for 1.2 and these were fixed for 1.1

What release notes would you like? A list of bugfixes / new feaures? Which open source projects do you think does this best? Whom should we emulate?

[eugenyshchelkanov]

Angular team does a good job of maintaining a changelog: https://github.com/angular/angular/blob/master/CHANGELOG.md

[wmekal]

Guys, seriously - please publish some release notes.

I'm updating packages in my project and I have Microsoft.Net.Compilers.1.0.

Is it safe to update to 2.0? What has changed? Should I expect any problems?

[JustinXinLiu]

We just found a bug in our UWP app in release mode only and it's magically fixed with the latest .net native compiler (1.6.3). However, we have no idea what caused it and without a proper release note, we cannot avoid issues like this in the future.

Please, release notes are not too much to ask here.

[jcouv]

Started some documentation of package versions: https://github.com/dotnet/roslyn/wiki/NuGet-packages
As far as breaking changes, you can find them in documents here: https://github.com/dotnet/roslyn/tree/master/docs/compilers/CSharp
We don't currently have a changelog aside from language features.

[eluchsinger]

Bump! Any news?

[jcouv]

Let me try to frame the problem to move this discussion forward. As far as I can tell, there are 3 kinds of questions:

1. what are new language versions, language features and compiler features were added?
2. what compat breaks where introduced? (Which seems the question raised by @wmekal)
3. what bugs were fixed?

The first one is answered by the blog announcements (C# 7.2), the compiler section in VS release notes, the NuGet package doc page, and language history or language features pages.
Those pages have largely overlapping information, and range in user-friendliness (blog is most accessible, NuGet packages or language status pages are less so).

The second one is answered by the log of breaking changes.

The third one is most challenging and seems the least worthwhile in my opinion.
It is more challenging due to volume of issues that get fixed. Consider the compiler changes in 15.5 and compiler issues resolved in 15.5 with over a hundred of items each. Note that the Angular CHANGELOG that was shared in the discussion earlier pretty much has this same information, but in a nicer format and with fewer items.
Besides sharing the link to this list, I'm not sure that trying to prettify or summarize it is worthwhile. If you encountered a specific bug, then you should already be following its individual status.
I could add such links to the listing on the NuGet package page, if there's a need.

As for @JustinXinLiu's question, that is a question for .NET Native (you should contact them by email at the address listed here). It may have been documented in VS release notes.

[jcouv]

Any comments on my analysis and proposal above?

In short:

• Language features, compiler features and language compat breaks, and package versions are documented.
• Fixed bugs are listed, although not in a pretty format. I will include the link to that list in other documents above, but I don't think we should spend much time trying to summarize that list.

Tagging all participants in the thread so far: @dmitry-shechtman @eluchsinger @JustinXinLiu @wmekal @jmarolf @mteper @eugenyshchelkanov

[bkoelman]

As an analyzer developer, Public API diffs between versions would be helpful, similar to NetStandard.

[jcouv]

Thanks @bkoelman. I hadn't thought of public APIs.
Let me check with Immo on how they produce pretty diffs. Currently, the best we have for this purpose looks like this: https://github.com/dotnet/roslyn/commit/5520eaccd5d22ae98a39a5f88120277f02097dbf
We don't currently publish such links, but we could. Would that work?

[bkoelman]

If all changes are in a single commit, yes. Although I recall there are/were some bugs in the analyser where some changes would go unnoticed. Maybe this tool helps?

[eluchsinger]

I understand it is a big challenge to write a changelog every time with possibly hundreds of bug fixes, etc. What is important for me is that everything worth saying is in one place, so that I can make decisions very easily. Also, I think it's kind of a standard that you put a CHANGELOG.md file in the repository. Probably the majority of the projects on GitHub have a changelog file nowadays (npm, Angular, node, ReactJS). Although you should note that the projects I have linked above are not the same kind of project as this is.

This is the reason why I ask you if you want to use this approach or not. Maybe it is not even possible because of the kind of this project.

[wmekal]

@jcouv Thanks for link to the log of breaking changes. This the minimum I expected.
Changelog.md file as @eluchsinger proposed would be very convenient even if it just contained links you pasted. This way every newcomer has a clear entry point instead of wandering where to search for information.

[jcouv]

I'll take a stab at a changelog. I'll start a PR and discuss with the team.
It would have: a couple highlights to new features, a link to breaking changes, a link to bug fixes and a link to API diff.

[wmekal]

Sounds good :)

[jcouv]

Took a stab: https://github.com/dotnet/roslyn/pull/24195

[jcouv]

Started a changelog in the wiki section, which only covers the compilers.
I may add a link to it from the README.md on the frontpage.

I'll go ahead and close this issue as resolved now. Thanks