Clarify expected compiler behavior with respect to RuntimeFeature querying

Author: Immo Landwerth

accepted/2021/preview-features/preview-features.md

@@ -179,36 +179,41 @@ dependencies ([discussed later](#api-analyzer)).
 
 ### Compilation context
 
-When `EnablePreviewFeatures` is true, the `LangVersion` property should be set
-to `Preview` (unless the customer has explicitly set `LangVersion` in their
-project file already). This avoids customers having to turn on preview features
-for the language separately.
+When `EnablePreviewFeatures` is true, the `LangVersion` property is set to
+`Preview` (unless the customer has explicitly set `LangVersion` in their project
+file already). This avoids customers having to turn on preview features for the
+language separately.
 
 In addition, the property `EnablePreviewFeatures` should be passed to the
 compilation context (akin to how `TargetFramework` is passed in today). An
 analyzer will use that to block use of APIs that are marked as preview as basing
 this off the language preview mode is nonsensical.
 
-***Note:*** F# doesn't have this capability today.
+The way the compiler knows which features a targeted runtime supports is by
+looking at the `RuntimeFeature` type. Each runtime feature corresponds to a
+specific field on that type. If the type doesn't have the field, the runtime is
+considered as not-supporting the feature. To indicate that a feature is there
+but requires turning on preview mode, we'll simply mark the field with the
+`[RequiresPreviewFeatures]` attribute, just like any other preview API.
 
-Since we use a separate property the user can have preview features off, but
-language is in preview mode. This would result in configuration where the user
-can use runtime features that are in preview.
+This solves two problems:
 
-We have two options on how we can deal with this:
+* The customer is using a future version of C# where a given language feature is
+  no longer considered "preview" and thus doesn't require `LangVersion` to be
+  set to preview but in the targeted runtime the feature is still preview. When
+  a language feature is used that requires the given runtime feature, the
+  compiler should check if the field is marked as preview and fail unless the
+  customer has turned preview mode on.
 
-1. One option is to use `RuntimeFeatures` and mark the field as
-   `[RequiresPreviewFeatures]` that causes the compiler to enforce the
-   containing assembly/type/member to be marked as `[RequiresPreviewFeatures]`
-   as well. Aleksey believes this check needs to be in-place regardless of
-   number of checks. Another option is to simply fail the build as an invalid
-   configuration.
+* The customer has manually set `LangVersion` to `Preview` but
+  `EnablePreviewFeatures` is not configured (thus defaulting to `False`).
+  Similar case as above, the customer can use any language feature that doesn't
+  require runtime changes but as soon as a feature is used that requires a
+  preview runtime feature, the compiler will report an error, demanding that
+  preview mode needs to be turned on.
 
-2. The other option is to simply fail the build with an error instructing the
-   customer that this configuration is invalid. This could be in MSBuild and
-   doesn't require work in the compiler.
-
-***OPEN QUESTION**: Do we want to use the first or the second mechanism?*
+***Note:*** F# doesn't have the capability to use analyzers today. We can
+decided to make this a compiler feature for F#.
 
 ### API Analyzer
 
@@ -451,3 +456,9 @@ preview features for the .NET platform:
 * Using this property might not work well for VB and F#
 * The biggest counter argument is that the compiler can be in stable version but
   the TFM you're targeting is not.
+* Due to the transitivity tracking, this can be a breaking change for anyone who
+  has set `LangVersion` to `Preview`. That's because today, the resulting binary
+  isn't marked as requiring callers to be in preview mode as well where we'd now
+  demand this to be the case. We could address this by only applying the new
+  behavior to code that is targeting .NET 6 (or higher), but this will likely
+  still bite folks that upgrade to .NET 6.