Release notes proposal (dotnet#16377)

nojaf · web-flow · commit 68fef88ca41e · 2023-12-14T11:22:03.000+01:00
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -9,17 +9,17 @@ Fixes # (issue, if applicable)
 - [ ] Test cases added
 - [ ] Performance benchmarks added in case of performance changes
 - [ ] Release notes entry updated:
-    > Please make sure to add an entry with short succint description of the change as well as link to this pull request to the respective release notes file, if applicable.
+    > Please make sure to add an entry with short succinct description of the change as well as link to this pull request to the respective release notes file, if applicable.
     >
     > Release notes files:
-    > - If anything under `src/Compiler` has been changed, please make sure to make an entry in `docs/release-notes/FSharp.Compiler.Service/<version>.md`, where `<version>` is usually "highest" one, e.g. `42.8.200`
-    > - If language feature was added (i.e. `LanguageFeatures.fsi` was changed), please add it to `docs/releae-notes/Language/preview.md`
-    > - If a change to `FSharp.Core` was made, please make sure to edit `docs/release-notes/FSharp.Core/<version>.md` where version is "highest" one, e.g. `8.0.200`.
+    > - If anything under `src/Compiler` has been changed, please make sure to make an entry in `docs/release-notes/.FSharp.Compiler.Service/<version>.md`, where `<version>` is usually "highest" one, e.g. `42.8.200`
+    > - If language feature was added (i.e. `LanguageFeatures.fsi` was changed), please add it to `docs/releae-notes/.Language/preview.md`
+    > - If a change to `FSharp.Core` was made, please make sure to edit `docs/release-notes/.FSharp.Core/<version>.md` where version is "highest" one, e.g. `8.0.200`.
 
-    > Examples of release notes entries:
-    > - Respect line limit in quick info popup - https://github.com/dotnet/fsharp/pull/16208
-    > - More inlines for Result module - https://github.com/dotnet/fsharp/pull/16106
-    > - Miscellaneous fixes to parens analysis - https://github.com/dotnet/fsharp/pull/16262
-    >
+    > Information about the release notes entries format can be found in the [documentation](https://fsharp.github.io/fsharp-compiler-docs/release-notes/About.html).
+    > Example:
+    > * More inlines for Result module. ([PR #16106](https://github.com/dotnet/fsharp/pull/16106))
+    > * Correctly handle assembly imports with public key token of 0 length. ([Issue #16359](https://github.com/dotnet/fsharp/issues/16359), [PR #16363](https://github.com/dotnet/fsharp/pull/16363))
+    > *`while!` ([Language suggestion #1038](https://github.com/fsharp/fslang-suggestions/issues/1038), [PR #14238](https://github.com/dotnet/fsharp/pull/14238))
 
     > **If you believe that release notes are not necessary for this PR, please add `NO_RELEASE_NOTES` label to the pull request.**
diff --git a/.github/workflows/check_release_notes.yml b/.github/workflows/check_release_notes.yml
@@ -85,10 +85,10 @@ jobs:
         [[ "$VISUAL_STUDIO_VERSION" =~ ^[0-9]+\.[0-9]+$ ]] || (echo "   Invalid Visual Studio Version parsed"; exit 1)
 
         _release_notes_base_path='docs/release-notes'
-        _fsharp_core_release_notes_path="${_release_notes_base_path}/FSharp.Core/${FSHARP_CORE_VERSION}.md"
-        _fsharp_compiler_release_notes_path="${_release_notes_base_path}/FSharp.Compiler.Service/${FSHARP_CORE_VERSION}.md"
-        _fsharp_language_release_notes_path="${_release_notes_base_path}/Language/preview.md"
-        _fsharp_vs_release_notes_path="${_release_notes_base_path}/VisualStudio/${VISUAL_STUDIO_VERSION}.md"
+        _fsharp_core_release_notes_path="${_release_notes_base_path}/.FSharp.Core/${FSHARP_CORE_VERSION}.md"
+        _fsharp_compiler_release_notes_path="${_release_notes_base_path}/.FSharp.Compiler.Service/${FSHARP_CORE_VERSION}.md"
+        _fsharp_language_release_notes_path="${_release_notes_base_path}/.Language/preview.md"
+        _fsharp_vs_release_notes_path="${_release_notes_base_path}/.VisualStudio/${VISUAL_STUDIO_VERSION}.md"
 
         readonly paths=(
             "src/FSharp.Core|${_fsharp_core_release_notes_path}"
diff --git a/docs/content/fsdocs-theme.css b/docs/content/fsdocs-theme.css
@@ -0,0 +1,3 @@
+﻿:root {
+    --main-menu-width: 300px;
+}
diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico
diff --git a/docs/release-notes/.FSharp.Compiler.Service/8.0.100.md b/docs/release-notes/.FSharp.Compiler.Service/8.0.100.md
@@ -0,0 +1,3 @@
+﻿### Fixed
+
+* Include the `get,set` keywords in the range of `SynMemberDefn.AutoProperty`. ([PR #15835](https://github.com/dotnet/fsharp/pull/15835))
diff --git a/docs/release-notes/.FSharp.Compiler.Service/8.0.200.md b/docs/release-notes/.FSharp.Compiler.Service/8.0.200.md
@@ -0,0 +1,8 @@
+### Fixed
+
+* Miscellaneous fixes to parentheses analysis. ([PR #16262](https://github.com/dotnet/fsharp/pull/16262), [PR #16391](https://github.com/dotnet/fsharp/pull/16391), [PR #16370](https://github.com/dotnet/fsharp/pull/16370), [PR #16395](https://github.com/dotnet/fsharp/pull/16395))
+* Correctly handle assembly imports with public key token of 0 length. ([Issue #16359](https://github.com/dotnet/fsharp/issues/16359), [PR #16363](https://github.com/dotnet/fsharp/pull/16363))
+
+### Added
+* Raise a new error when interfaces with auto properties are implemented on constructor-less types. ([PR #16352](https://github.com/dotnet/fsharp/pull/16352))
+* Allow usage of `[<TailCall>]` with older `FSharp.Core` package versions. ([PR #16373](https://github.com/dotnet/fsharp/pull/16373))
diff --git a/docs/release-notes/.FSharp.Core/8.0.200.md b/docs/release-notes/.FSharp.Core/8.0.200.md
@@ -0,0 +1,3 @@
+### Added
+
+* More inlines for Result module. ([PR #16106](https://github.com/dotnet/fsharp/pull/16106))
diff --git a/docs/release-notes/.Language/8.0.md b/docs/release-notes/.Language/8.0.md
@@ -0,0 +1,3 @@
+﻿### Added
+
+* `while!` ([Language suggestion #1038](https://github.com/fsharp/fslang-suggestions/issues/1038), [PR #14238](https://github.com/dotnet/fsharp/pull/14238))
diff --git a/docs/release-notes/.Language/preview.md b/docs/release-notes/.Language/preview.md
@@ -0,0 +1,4 @@
+### Added
+
+* Better generic unmanaged structs handling. ([Language suggestion #692](https://github.com/fsharp/fslang-suggestions/issues/692), [PR #12154](https://github.com/dotnet/fsharp/pull/12154))
+* Bidirectional F#/C# interop for 'unmanaged' constraint. ([PR #12154](https://github.com/dotnet/fsharp/pull/12154))
diff --git a/docs/release-notes/.aux/Common.fsx b/docs/release-notes/.aux/Common.fsx
@@ -0,0 +1,49 @@
+﻿#r "nuget: Markdig, 0.33.0"
+#r "nuget: FsHttp, 12.1.0"
+
+open System.IO
+open System.Xml.Linq
+open System.Text.RegularExpressions
+open FsHttp
+
+let versionProps = Path.Combine(__SOURCE_DIRECTORY__, "../../../eng/Versions.props")
+let versionPropsDoc = XDocument.Load(versionProps)
+
+/// Find all published versions of a package on NuGet
+let getAvailableNuGetVersions (packageName: string) : Set<string> =
+    let packageName = packageName.ToLowerInvariant()
+
+    http { GET $"https://api.nuget.org/v3-flatcontainer/%s{packageName}/index.json" }
+    |> Request.send
+    |> Response.deserializeJson<{| versions: string array |}>
+    |> fun json -> Set.ofArray json.versions
+
+/// Try and find the publish date on NuGet
+let tryGetReleaseDate (packageName: string) (version: string) : string option =
+    let packageName = packageName.ToLowerInvariant()
+
+    http { GET $"https://api.nuget.org/v3/registration5-gz-semver2/%s{packageName}/%s{version}.json" }
+    |> Request.send
+    |> Response.deserializeJson<{| published: string |}>
+    |> fun json ->
+        if System.String.IsNullOrWhiteSpace json.published then
+            None
+        else
+            Some(json.published.Split('T').[0])
+
+/// In order for the heading to appear in the page content menu in fsdocs,
+/// they need to follow a specific HTML structure.
+let transformH3 (version: string) (input: string) : string =
+    let pattern = "<h3>(.*?)</h3>"
+
+    let replacement =
+        $"<h3><a name=\"%s{version}-$1\" class=\"anchor\" href=\"#%s{version}-$1\">$1</a></h3>"
+
+    Regex.Replace(input, pattern, replacement)
+
+/// Process all MarkDown files from the given release folder
+let processFolder (path: string) (processFile: string -> string) : string =
+    Directory.EnumerateFiles(path, "*.md")
+    |> Seq.sortByDescending Path.GetFileNameWithoutExtension
+    |> Seq.map processFile
+    |> String.concat "\n"
diff --git a/docs/release-notes/About.md b/docs/release-notes/About.md
@@ -0,0 +1,62 @@
+﻿---
+category: Release Notes
+categoryindex: 600
+index: 1
+title: About
+---
+
+# About
+
+The release notes for the [F\# language](./Language.md), [FSharp.Core](./FSharp.Core.md) and [FSharp.Compiler.Service](./FSharp.Compiler.Service.md) are based on the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.  
+The target audience of these release notes are the respective end-users.
+
+## Writing a changelog entry
+
+In order to keep the change logs consistent the following format was proposed for each entry:
+
+```md
+* <Informative description>. ([PR #16106](https://github.com/dotnet/fsharp/pull/16106))
+```
+
+Some tips:
+
+* Use valid [Markdown](https://www.markdownguide.org/).
+* Use `*` as bullet point symbol. We don't want to mix `*` and `-`.
+* Start your description with a capital and end the sentence with a dot.
+* **Always** include a link to your pull request before the closing `)`, `([PR #16106](https://github.com/dotnet/fsharp/pull/16106))`.
+* Optionally, include a link to an issue on `dotnet/fsharp` use `Issue #number` before the link to the pull request.  
+
+Example:
+
+```md
+* Correctly handle assembly imports with public key token of 0 length. ([Issue #16359](https://github.com/dotnet/fsharp/issues/16359), [PR #16363](https://github.com/dotnet/fsharp/pull/16363))
+```
+
+* Optionally, include a link to a language suggestion from  `dotnet/fsharp` use `Language suggestion #number` before the link to the pull request.
+
+Example:
+
+```md
+* `while!` ([Language suggestion #1038](https://github.com/fsharp/fslang-suggestions/issues/1038), [PR #14238](https://github.com/dotnet/fsharp/pull/14238))
+```
+
+* Choose the right section for your type of change. (`## Added`, `## Changed`, `## Deprecated`, `## Removed`, `## Fixed` or `## Security`).
+* Ensure your description makes it clear what the change is about. The reader should be informed on a high level without needing to click through the pull request link and find out in the code what actually changed.
+* Maintainers or other contributors might rewrite your changelog entry in the future. This might be done when multiple pull requests can be consolidated under the same umbrella.
+* Related pull requests can be listed in the same entry when it makes sense.
+
+Example:
+
+```md
+* Miscellaneous fixes to parentheses analysis. ([PR #16262](https://github.com/dotnet/fsharp/pull/16262), [PR #16391](https://github.com/dotnet/fsharp/pull/16391), [PR #16370](https://github.com/dotnet/fsharp/pull/16370))
+```
+
+## The release process
+
+### General
+
+How does it work? Different stages/phases?
+
+#### FSharp.Compiler.Service
+
+Perhaps add some specific info if available?
diff --git a/docs/release-notes/FSharp.Compiler.Service.fsx b/docs/release-notes/FSharp.Compiler.Service.fsx
@@ -0,0 +1,47 @@
+(** ---
+category: Release Notes
+categoryindex: 600
+index: 4
+title: FSharp.Compiler.Service
+---
+
+# FSharp.Compiler.Service
+*)
+(*** hide ***)
+#load "./.aux/Common.fsx"
+
+open System.IO
+open System.Xml.XPath
+open Markdig
+open Common
+
+let path = Path.Combine(__SOURCE_DIRECTORY__, ".FSharp.Compiler.Service")
+let fcsMajorVersion = versionPropsDoc.XPathSelectElement("//FCSMajorVersion").Value
+let nugetPackage = "FSharp.Compiler.Service"
+let availableNuGetVersions = getAvailableNuGetVersions nugetPackage
+
+processFolder path (fun file ->
+    let versionInFileName = Path.GetFileNameWithoutExtension(file)
+    // Example: 8.0.200
+    let versionParts = versionInFileName.Split '.'
+
+    let version = $"%s{fcsMajorVersion}.%s{versionParts.[0]}.%s{versionParts.[2]}"
+    // TODO: Can we determine if the current version is in code freeze based on the Version.props info?
+    let title =
+        if not (availableNuGetVersions.Contains version) then
+            $"%s{version} - Unreleased"
+        else
+            match tryGetReleaseDate nugetPackage version with
+            | None -> $"%s{version} - Unreleased"
+            | Some d -> $"%s{version} - %s{d}"
+
+    let nugetBadge =
+        if not (availableNuGetVersions.Contains version) then
+            System.String.Empty
+        else
+            $"<a href=\"https://www.nuget.org/packages/%s{nugetPackage}/%s{version}\" target=\"_blank\"><img alt=\"Nuget\" src=\"https://img.shields.io/badge/NuGet-%s{version}-blue\"></a>"
+
+    let content = File.ReadAllText file |> Markdown.ToHtml |> transformH3 version
+
+    $"""<h2><a name="%s{version}" class="anchor" href="#%s{version}">%s{title}</a></h2>%s{nugetBadge}%s{content}""")
+(*** include-it-raw ***)
diff --git a/docs/release-notes/FSharp.Compiler.Service/8.0.200.md b/docs/release-notes/FSharp.Compiler.Service/8.0.200.md
diff --git a/docs/release-notes/FSharp.Core.fsx b/docs/release-notes/FSharp.Core.fsx
@@ -0,0 +1,42 @@
+﻿(** ---
+category: Release Notes
+categoryindex: 600
+index: 3
+title: FSharp.Core
+---
+
+# FSharp.Core
+*)
+(*** hide ***)
+#load "./.aux/Common.fsx"
+
+open System.IO
+open Markdig
+open Common
+
+let path = Path.Combine(__SOURCE_DIRECTORY__, ".FSharp.Compiler.Service")
+let nugetPackage = "FSharp.Core"
+let availableNuGetVersions = getAvailableNuGetVersions nugetPackage
+
+processFolder path (fun file ->
+    let version = Path.GetFileNameWithoutExtension(file)
+
+    // TODO: Can we determine if the current version is in code freeze based on the Version.props info?
+    let title =
+        if not (availableNuGetVersions.Contains version) then
+            $"%s{version} - Unreleased"
+        else
+            match tryGetReleaseDate nugetPackage version with
+            | None -> $"%s{version} - Unreleased"
+            | Some d -> $"%s{version} - %s{d}"
+
+    let nugetBadge =
+        if not (availableNuGetVersions.Contains version) then
+            System.String.Empty
+        else
+            $"<a href=\"https://www.nuget.org/packages/%s{nugetPackage}/%s{version}\" target=\"_blank\"><img alt=\"Nuget\" src=\"https://img.shields.io/badge/NuGet-%s{version}-blue\"></a>"
+
+    let content = File.ReadAllText file |> Markdown.ToHtml |> transformH3 version
+
+    $"""<h2><a name="%s{version}" class="anchor" href="#%s{version}">%s{title}</a></h2>%s{nugetBadge}%s{content}""")
+(*** include-it-raw ***)
diff --git a/docs/release-notes/FSharp.Core/8.0.200.md b/docs/release-notes/FSharp.Core/8.0.200.md
diff --git a/docs/release-notes/Language.fsx b/docs/release-notes/Language.fsx
@@ -0,0 +1,35 @@
+﻿(** ---
+category: Release Notes
+categoryindex: 600
+index: 2
+title: F# Language
+---
+
+# F\# Language
+*)
+(*** hide ***)
+#load "./.aux/Common.fsx"
+
+open System.IO
+open Markdig
+open Common
+
+let path = Path.Combine(__SOURCE_DIRECTORY__, ".Language")
+
+Directory.EnumerateFiles(path, "*.md")
+|> Seq.sortWith (fun a b ->
+    let a = Path.GetFileNameWithoutExtension a
+    let b = Path.GetFileNameWithoutExtension b
+
+    match a, b with
+    | "preview", "preview" -> 0
+    | "preview", _ -> -1
+    | _, "preview" -> 1
+    | _, _ -> compare (int b) (int a))
+|> Seq.map (fun file ->
+    let version = Path.GetFileNameWithoutExtension(file)
+    let version = if version = "preview" then "Preview" else version
+    let content = File.ReadAllText file |> Markdown.ToHtml |> transformH3 version
+    $"""<h2><a name="%s{version}" class="anchor" href="#%s{version}">%s{version}</a></h2>%s{content}""")
+|> String.concat "\n"
+(*** include-it-raw ***)
diff --git a/docs/release-notes/Language/preview.md b/docs/release-notes/Language/preview.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+:root {`
	`2`	`+ --main-menu-width: 300px;`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+### Fixed`
	`2`	`+`
	`3`	+* Include the `get,set` keywords in the range of `SynMemberDefn.AutoProperty`. ([PR #15835](https://github.com/dotnet/fsharp/pull/15835))
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+### Added`
	`2`	`+`
	`3`	`+* More inlines for Result module. ([PR #16106](https://github.com/dotnet/fsharp/pull/16106))`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+### Added`
	`2`	`+`
	`3`	+* `while!` ([Language suggestion #1038](https://github.com/fsharp/fslang-suggestions/issues/1038), [PR #14238](https://github.com/dotnet/fsharp/pull/14238))