Improve FCS docs - #20508
Merged
Merged
Improve FCS docs#20508
Conversation
The literate scripts under docs/fcs no longer compiled against the current FSharp.Compiler.Service, so the published tutorial pages rendered compiler errors instead of output. fsdocs 23 surfaces script evaluation failures rather than discarding them, which made this visible. - tokenizer.fsx: FSharpSourceTokenizer takes three arguments now, drop the trailing None and describe the language version argument. - editor.fsx: FSharpMethodGroupItemParameter.Display is a RichText, so read its Text instead of enumerating tagged parts. - typedtree.fsx: annotate the input as string to disambiguate the new File.WriteAllText(string, ReadOnlySpan<char>) overload. - untypedtree.fsx: SynExpr.LetOrUse is a SynLetOrUse record and SynModuleDecl.Let gained a trivia field. - untypedtree-apis.fsx: SynComponentInfo lost its longId field in dotnet#19602, use the LongIdent compatibility member.
The release notes pages derived the package version from the notes file name, which no longer holds. FSharp.Compiler.Service bumps its minor version independently of the F# version (43.12.100 is F# 11.0.100 while 43.12.204 is F# 10.0.204), and FSharp.Core 10.0.2xx and 10.0.3xx shipped as 10.1.x. Recent headings therefore named versions that do not exist and showed as unreleased. Each package on NuGet is now matched to its notes file through the source commit recorded in its nuspec: eng/Versions.props at that commit (under src/fsharp for VMR builds) gives the exact F# version. The heading shows the first package that shipped for the notes, with a badge per servicing rebuild, and the page is ordered by package version. Also: - Sort versions numerically instead of as strings, so 10.x and 11.x no longer sort below 9.x. The Language page had a broken comparer that threw on three-part versions and rendered nothing. - Distinguish unlisted packages, which NuGet reports with a 1900-01-01 publish date, from ones that are not on NuGet at all. - Silence FsHttp request logging and bump Markdig and FsHttp.
Twelve pages had no fsdocs front matter, so the published site listed them in an unnamed "Other" group at the bottom of the navigation. The postmortems get their own "Postmortems" category, with the README as the overview. The remaining pages join the existing categories: the equality optimizations, regression testing, LabelOps, perf archive and SRTP guide under Compiler Internals, the LSP proposal under Language Service Internals, reflection-free printing under FSharp.Core and the pending breaking changes under Release Notes. The postmortem skill now tells the agent to emit that front matter, and the postmortems README no longer links to ../../.github, which cannot resolve on the site. The "running the documentation locally" guide is rewritten for the build.fsx pipeline in fsharp-compiler-docs and its FSHARP_REPO variable, and documents how fsdocs watch caches pages and why edits to the release-notes markdown are not picked up.
Contributor
|
nojaf
added
the
NO_RELEASE_NOTES
github-actions
Bot
added
the
⚠️ Affects-Agent-Config
Contributor
|
🔍 Tooling Safety Check — Affects-Agent-Config
|
Member
|
A nice package of cleanups and improvements, thank you 👍 ! |
T-Gro
approved these changes
Sep 10, 2026
github-project-automation
Bot
moved this from New
to In Progress
in F# Compiler and Tooling
github-project-automation
Bot
moved this from In Progress
to Done
in F# Compiler and Tooling
This was referenced Sep 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hello @T-Gro, sorry for ignoring the PR template. I'm gonna yap a bit.
This is PR purely about the docs over at https://fsharp.github.io/fsharp-compiler-docs/
So, earlier today I fixed the GitHub Action that automatically publishes these (see fsharp/fsharp-compiler-docs#1018)
And I noticed a few small things I wanted to fix in this PR:
And some newer pages like the postmortems and LSP did not have frontmatter and did not end up in their own section. I changed that (and updated the skill as well)
I also bumped the fsdocs-tool to 23.alpha.1, I'm not sure if you need anything on MS side to allow that tool version to be used. But really, it is worth it:
In
docs/release-notes/.aux/Common.fsxI also bumped some NuGet package versions. Not sure if that part matters much for this repo.I hope this works for you.