Fsharp: Where's the FSharp.Core changelog?

[cmeeren]

This may be a stupid question, but I can't find any updated changelog for the FSharp.Core nuget package. I noticed 4.3 is out and was wondering what's new from 4.2 in order to determine whether to upgrade.

[cmeeren]

Haha, just googled my own issue now that 4.5 has been released. Is there seriously no FSharp.Core changelog?

[abelbraaksma]

I miss it too. Sometimes things get mentioned in VS updates 'what's changed' pages, but often that list is incomplete at best. Also, changes in compiler are hard to find, but they are there. I recently stumbled on a change in SRTP which allowed class names in the restriction. It's not mentioned anywhere (except that it's been added to the docs).

I would certainly welcome a change log on the compiler, language service and Core lib.

[cartermp]

Sorry, I hadn't seen this issue.

Changelogs are captured as RFCs. When there is a new release, relevant RFCs are merged and organized appropriately.

Though bug fixes are not. We can consider a bugfix-level changelog. @KevinRansom / @dsyme / @TIHan / @brettfo ?

[abelbraaksma]

@cartermp, Since many small new features are implemented as bugfixes rather than through the RFC process, that seems reasonable. And it's _especially_ bugfixes that I would be interested in, a place to look if your favorite (read that as: production blocking) bug is (partially) resolved would be of tremendous help. Even an incomplete list would already be beneficial, I think.

Since many bugs are reported multiple times, and people often know their own bugs, this may go a long way in people cleaning up lingering or forgotten bug reports. I've done that once (going over my old bugs and re-assessing them), but it is currently a non-trivial task since there isn't a list of fixes.

I've sometimes went over existing bugs, following the relevant PR's, trying to find out which made it into which VS version or RTM version of FSharp.Core or the language services, but that is an arduous task and often leads to a dead end.

Visual studio does something like this: in the "What's new" it lists the relevant user-reported bugs that were addressed in a given release. Perhaps we could collect amd add our list there too?

[cartermp]

@abelbraaksma Could you give an example of this?

Since many small new features are implemented as bugfixes rather than through the RFC process, that seems reasonable

I'm not aware of smaller new features being added alongside bug fixes. New features are captured via an RFC, and behavioral changes have been captured in the Visual Studio release notes. I think it's worth putting those behavioral changes in a changelog as well, but it's not clear where that changelog ought to live, either. My guess is somewhere under the fsharp org on GitHub.

[dsyme]

Since many small new features are implemented as bugfixes rather than through the RFC process

All design-changes should be in an RFC, lete us know if that's not the case

[abelbraaksma]

@cartermp, @dsyme, I may be wrong, let me check. It may be my misunderstanding of the process, or when something gets a label "feature-improvement" and then a PR, but no linked RFC. That doesn't necessarily mean there is none.

I guess that performance improvements are neither (not bugs, not in need of RFC's, i.e. #5131) and the same may be true for improving error messages (for istance, #5114, #5983, the latter being substantive). None has an RFC, none of these PR's is addressing a 'real" bug, but they are important improvements people would definitely want to know about.

Also, #4947 (add .NET versions support) seems an important new feature, or improvement of existing ones, but there's no RFC (and I can see why not, but still, it is important to get these feature improvements known to users).

[cartermp]

@abelbraaksma None of these are FSharp.Core changes. One is a tooling change (which are captured in VS release notes), one is a compiler error change (also captured there), and the other is also a tooling change _proposal_ (and one that we won't be taking any time soon).

This issue is for FSharp.Core. I see value in there being a changelog for this, but the question is where that changelog lies.

[cmeeren]

Changelogs are captured as RFCs. When there is a new release, relevant RFCs are merged and organized appropriately.

Most of the "F# 4.5 candidate RFCs" are currently just marked as "approved in principle", so that list does not seem to me to be actively maintained (even apart from the fact that they're listed as "candidates"). I suppose someone goes through them after the fact and edits the RFCs to reflect what has actually been implemented, and how it actually turned out?

In any case, to be frank, when a new F# version comes out, I don't really want to dig up and read through a bunch of design documents to find out what's changed. I just want a list of new features and how to use them (and a list of bug fixes). This can appear on the .NET blog for all I care, or another post on an MS-owned domain. (By all means though, do link to the RFCs from the changelog if they contain useful information.)

C# manages to communicate new features very clearly in several channels. I think an F# changelog could help push F# adoption – it would be one less thing implying that F# is the "lesser child".

(Thanks for the great work on the language, though! 😁👍 I'd just like to know what it was.)

[cartermp]

@cmeeren Every RFC that is implemented is in a folder that corresponds to a version. You can see everything going into F# 4.5 in the FSharp-4.5 and FSharp.Core-4.5.0.0 folders. Unreleased features and/or in-progress features are in the RFCs folder.

We also do capture release notes for all changes to the language and FSharp.Core in the Visual Studio release notes. For example: https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2017-relnotes#fsharp

Each of the changes that make their way into the binary/package for FSharp.Core are documented in these release notes when they are shipped.

I think the question is if we should publish changes to FSharp.Core separately from what we already do. And perhaps the same to the language and/or compiler.

[cmeeren]

@cmeeren Every RFC that is implemented is in a folder that corresponds to a version. You can see everything going into F# 4.5 in the FSharp-4.5 and FSharp.Core-4.5.0.0 folders. Unreleased features and/or in-progress features are in the RFCs folder.

Ah, I see. I followed the link in the readme called "Open F# Language RFCs (including candidates for F# 4.5)". Thanks for the clarification.

[abelbraaksma]

@cartermp yes, I always read those release notes trying find out wether it's worthwhile to go through an update process for all instances. Often the list is empty, even when clearly bug fixes made it through. However, I think that list, while helpful, is often incomplete when it is available. I've had several discussions here only to find out that something was already implemented or was planned for version X. An example is the SRTP change mentioned nowhere. I know release management is difficult, and I wasn't aware of the folders. Perhaps we can link there from the Release Notes of VS?

[cmeeren]

Perhaps we can link there from the Release Notes of VS?

I also suggest clearly linking there from the readme in this repo too, since this is where the "project page" link from the FSharp.Core points.

[cartermp]

@abelbraaksma

Often the list is empty, even when clearly bug fixes made it through.

When the list is empty, then a fix for F# is not in that update. If either one of these is true:

• A fix for F# went into a release and it's not listed
• A fix for F# did not go into a release and it is listed

Then that is a mistake on our end that needs to be corrected. I corrected one such mistake for the VS 15.7.3 update. But in general, we've documented every change that includes a fix for F#. For example:

• 15.7.2 includes a fix for ASP.NET Core projects and for the SqlCommandProvider

Note that 15.7.3 does not list F# because it does not include a change to the F# compiler, core library, or tools, so there is nothing listed for 15.7.3 now.

However, I think that list, while helpful, is often incomplete when it is available. I've had several discussions here only to find out that something was already implemented or was planned for version X.

I'm not sure what incomplete means here.

At the time of a release, a set of changes is taken in. These changes are documented in the VS release notes (sans bug fixes unless they are severe and/or quite customer-facing). Some change may not make it into that release, so a bug is fixed but not available for people yet.

Additionally, we strive to add the proper milestone to an issue so that you can look through those and see if something is within that particular release. This is an area we can absolutely improve.

Do you feel that a document which is entirely separate from the Visual Studio release notes helps in discovery of changes that have gone in, but are not yet available for people? I don't personally see this as different than searching the commit log or PR history of this repository to see if a given thing is fixed or not, but if you feel that it helps with discoverability of this scenario, then that's good feedback.

An example is the SRTP change mentioned nowhere.

Every behavioral change we have made to SRTP has been documented in VS release notes, as far as I know. Do you have an example where this is not true?

[cartermp]

I've gone through and applied milestones on issues where they were released back until 15.6. Not sure if I'll do so for 15.5 and before, but this should cover any relatively recent concerns.

[abelbraaksma]

I've gone through and applied milestones on issues where they were released back until 15.6.

@cartermp That's absolutely fantastic! Thanks. I don't think it is necessary to go further back, but doing this consistently would go a long way!

In addition, for future releases, a link in the Release Notes that queries the relevant GitHub issues in fslang and visualfsharp would probably help other customers, since many may not be aware of how to find and/or query for the milestones.

I'm not sure what incomplete means here.

Me neither ;). It's just that I have had the pleasant experience to find certain bugs gone (good!), then went on to look from what version that was (through Release Notes), but couldn't find it. For instance, I'm still at a loss about this one, which I believe wasn't mentioned, but I may have simply missed it:

Starting with F# 4.1, you can also specify concrete type names in statically resolved type parameter signatures. (from docs on SRTP)

Since the information in Docs is fairly limited, I hoped to find the original discussion, to understand better the use cases it solves. I encountered this by accident from a comment by Don where he used this syntax, which looked unfamiliar to me at the time.

I'm not saying you'd have to go back all the way to find this, I've meanwhile come to understand how to apply this new feature. But it left me wondering whether other functionalities also went unmentioned and therefor unnoticed (and in turn, that would lead to people not using new functionality, since they simply don't know it exists).

And today I found out about a new feature that I didn't see mentioned anywhere, but it is possible it is not F# specific or that I just don't know the proper terminology: the new inline shady comments on signatures (which isn't working very well yet, but I've reported that already):

[cartermp]

Closing this in favor of #5489