FSharp docs expose pre-release functionality

[MABowser]

fsharp-core-docs/.github/workflows/docs.yml

Line 29 in 7d5b804

run: git clone https://github.com/dotnet/fsharp --depth 1 fsharp -b main

My main question is: Is it intentional to have the docs show pre-release functionality?

I was writing a little app and forgot some syntax when using map. I checked the docs and noticed that it exposed a Keys property. I tried to use that instead of what I was doing. After a bit of poking to see if I was somehow missing a namespace I was helped by another engineer who said that Keys is a dotnet 6 feature. I then tried to answer the question "What of this can I use, and what can't I use yet?" which I was unable to do easily.

If this isn't intentional, I could see a number of ways to help:

• Build the docs not off of main, but off a release branch.
• Build off the main branch, but leave it to maintainers to mark functionality "pre-release" through an attribute and remove them when the functionality reaches the current dotnet version
• This would probably be a larger effort, but enhance the docs so they can be contextual based on the dotnet version similar to how the Microsoft docs here work

[baronfel]

I would suggest changing the target branch to the release/dev16.10 branch as the best fix, and then when .net 6 releases move to the release/dev17.0 branch alongside that.

One downside of this is that we do not get quite as up to date feedback as to the documentation status of new features/changed xml documentation, but that's probably acceptable given that these changes aren't deployed to the wider world yet.

[dsyme]

My preference is to not worry about this for now - mainly because of the size of the docs backlogs we have, particularly w.r.t. examples. This is because building off "main" allows us to incorporate latest doc updates for examples - we are restricted in integrating across to release/dev16.0. I tried to convince the dotnet/fsharp folk to have post-hoc updatable docs branches, e.g. docs/main, docs/dev16.0 which we could incorporate into code flow auto merging but didn't convince them partly because of the large number of auto-merge notifications that happen in the repo when you do that.

So my feeling is that we should revisit this once we have completed doc revisions (especially examples) for all of FSharp.Core.

[cartermp]

Yeah, this is not much of a deal IMO. They're usually very little changes in fsharp.core from release to release, and even if there was a substantial change, the vast majority of what people will want to look up is already GA. I would put this near the back of the list of things to solve