diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6642e4b7df6..f3fc39c1ec7 100644 --- 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/.md`, where `` 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/.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/.md`, where `` 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/.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.** \ No newline at end of file diff --git a/.github/workflows/check_release_notes.yml b/.github/workflows/check_release_notes.yml index 14b3c85ca51..8ffc85d0950 100644 --- 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 new file mode 100644 index 00000000000..78b11777baf --- /dev/null +++ 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 new file mode 100644 index 00000000000..ad06a8a2803 Binary files /dev/null and b/docs/img/favicon.ico differ diff --git a/docs/release-notes/.FSharp.Compiler.Service/8.0.100.md b/docs/release-notes/.FSharp.Compiler.Service/8.0.100.md new file mode 100644 index 00000000000..a1bc082b81c --- /dev/null +++ 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)) \ No newline at end of file diff --git a/docs/release-notes/.FSharp.Compiler.Service/8.0.200.md b/docs/release-notes/.FSharp.Compiler.Service/8.0.200.md new file mode 100644 index 00000000000..f77a4a7613f --- /dev/null +++ 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 `[]` 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 new file mode 100644 index 00000000000..e927a03a062 --- /dev/null +++ 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 new file mode 100644 index 00000000000..ad829f0a6b9 --- /dev/null +++ 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)) \ No newline at end of file diff --git a/docs/release-notes/.Language/preview.md b/docs/release-notes/.Language/preview.md new file mode 100644 index 00000000000..177436a2b43 --- /dev/null +++ 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)) \ No newline at end of file diff --git a/docs/release-notes/.aux/Common.fsx b/docs/release-notes/.aux/Common.fsx new file mode 100644 index 00000000000..ec9bd35101c --- /dev/null +++ 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 = + 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 = "

(.*?)

" + + let replacement = + $"

$1

" + + 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 new file mode 100644 index 00000000000..20e5138533c --- /dev/null +++ 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 +* . ([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? \ No newline at end of file diff --git a/docs/release-notes/FSharp.Compiler.Service.fsx b/docs/release-notes/FSharp.Compiler.Service.fsx new file mode 100644 index 00000000000..fc116d572cf --- /dev/null +++ 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 + $"\"Nuget\"" + + let content = File.ReadAllText file |> Markdown.ToHtml |> transformH3 version + + $"""

%s{title}

%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 deleted file mode 100644 index eee6e9d09e3..00000000000 --- a/docs/release-notes/FSharp.Compiler.Service/8.0.200.md +++ /dev/null @@ -1,7 +0,0 @@ -- Parens analysis: miscellaneous fixes - https://github.com/dotnet/fsharp/pull/16262 -- Parens analysis: keep parentheses around non-struct tuples in `&` patterns - https://github.com/dotnet/fsharp/pull/16391 -- Parens analysis: fix some parenthesization corner-cases in record expressions - https://github.com/dotnet/fsharp/pull/16370 -- Parens analysis: keep parens in method calls in dot-lambdas - https://github.com/dotnet/fsharp/pull/16395 -- Fixes #16359 - correctly handle imports with 0 length public key tokens - https://github.com/dotnet/fsharp/pull/16363 -- Raise a new error when interfaces with auto properties are implemented on constructor-less types - https://github.com/dotnet/fsharp/pull/16352 -- Allow usage of `[]` with older `FSharp.Core` package versions - https://github.com/dotnet/fsharp/pull/16373 diff --git a/docs/release-notes/FSharp.Core.fsx b/docs/release-notes/FSharp.Core.fsx new file mode 100644 index 00000000000..521ef4f630c --- /dev/null +++ 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 + $"\"Nuget\"" + + let content = File.ReadAllText file |> Markdown.ToHtml |> transformH3 version + + $"""

%s{title}

%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 deleted file mode 100644 index 8bed6454108..00000000000 --- a/docs/release-notes/FSharp.Core/8.0.200.md +++ /dev/null @@ -1 +0,0 @@ -- More inlines for Result module - https://github.com/dotnet/fsharp/pull/16106 \ No newline at end of file diff --git a/docs/release-notes/Language.fsx b/docs/release-notes/Language.fsx new file mode 100644 index 00000000000..73c173e7774 --- /dev/null +++ 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 + $"""

%s{version}

%s{content}""") +|> String.concat "\n" +(*** include-it-raw ***) diff --git a/docs/release-notes/Language/preview.md b/docs/release-notes/Language/preview.md deleted file mode 100644 index 7d9996a870e..00000000000 --- a/docs/release-notes/Language/preview.md +++ /dev/null @@ -1 +0,0 @@ -- Feature: Better unmanaged structs handling - https://github.com/dotnet/fsharp/pull/12154 \ No newline at end of file