Emphasize concerns with latest LangVersion (#42639)

BillWagner · WeihanLi · web-flow · commit a75a614029d7 · 2024-09-26T15:27:05.000-04:00
* Emphasize concerns with `latest` `LangVersion` Fixes #42400 Add more emphasis to discourage use of `latest` as the `LangVersion` element: - Change the style to `WARNING` - Add that `latest` can use a different language version on different machines. - Add that note and link from other C# docs discussing versioning. * Update docs/csharp/language-reference/language-versioning.md Co-authored-by: Weihan Li <7604648+WeihanLi@users.noreply.github.com> --------- Co-authored-by: Weihan Li <7604648+WeihanLi@users.noreply.github.com>
diff --git a/docs/csharp/language-reference/compiler-options/language.md b/docs/csharp/language-reference/compiler-options/language.md
@@ -1,7 +1,7 @@
 ---
 description: "C# Compiler Options for language feature rules. These options control how the compiler interprets certain language constructs."
 title: "Compiler Options - language feature rules"
-ms.date: 10/30/2023
+ms.date: 09/17/2024
 f1_keywords:
   - "cs.build.options"
 helpviewer_keywords:
@@ -65,6 +65,10 @@ This option specifies the names of one or more symbols that you want to define.
 
 The default language version for the C# compiler depends on the target framework for your application and the version of the SDK or Visual Studio installed. Those rules are defined in [C# language versioning](../language-versioning.md#defaults).
 
+> [!WARNING]
+>
+> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
+
 The **LangVersion** option causes the compiler to accept only syntax that is included in the specified C# language specification, for example:
 
 ```xml
@@ -75,9 +79,6 @@ The following values are valid:
 
 [!INCLUDE [lang-versions-table](../includes/langversion-table.md)]
 
-> [!IMPORTANT]
-> The `latest` value is generally not recommended. With `latest`, the compiler enables the latest features, even if those features depend on updates not included in the configured target framework.
-
 ### Considerations
 
 - To ensure that your project uses the default compiler version recommended for your target framework, don't use the **LangVersion** option. You can update the target framework to access newer language features.
diff --git a/docs/csharp/language-reference/configure-language-version.md b/docs/csharp/language-reference/configure-language-version.md
@@ -1,12 +1,16 @@
 ---
 title: Configure language version
-description: Learn how to override the default C# language version manually.
+description: Learn how to override the default C# language version manually. The C# compiler can support any language version up to the version in the installed SDK.
 ms.custom: "updateeachrelease"
-ms.date: 08/02/2024
+ms.date: 09/17/2024
 ---
 
 # Configure C# language version
 
+> [!WARNING]
+>
+> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
+
 If you must specify your C# version explicitly, you can do so in several ways:
 
 - Manually edit the [project file](#edit-the-project-file).
diff --git a/docs/csharp/language-reference/language-versioning.md b/docs/csharp/language-reference/language-versioning.md
@@ -2,14 +2,14 @@
 title: Language versioning
 description: Learn about how the C# language version is determined based on your project and the reasons behind that choice.
 ms.custom: "updateeachrelease"
-ms.date: 08/02/2024
+ms.date: 09/17/2024
 ---
 
 # C# language versioning
 
 The latest C# compiler determines a default language version based on your project's target framework or frameworks. Visual Studio doesn't provide a UI to change the value, but you can change it by editing the *csproj* file. The choice of default ensures that you use the latest language version compatible with your target framework. You benefit from access to the latest language features compatible with your project's target. This default choice also ensures you don't use a language that requires types or runtime behavior not available in your target framework. Choosing a language version newer than the default can cause hard to diagnose compile-time and runtime errors.
 
-[C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. [C# 11](../whats-new/csharp-11.md) is supported only on .NET 7 and newer versions. [C# 10](../whats-new/csharp-10.md) is supported only on .NET 6 and newer versions.
+[C# 13](../whats-new/csharp-13.md) is supported only on .NET 9 and newer versions. [C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. [C# 11](../whats-new/csharp-11.md) is supported only on .NET 7 and newer versions.
 
 Check the [Visual Studio platform compatibility](/visualstudio/releases/2022/compatibility#-visual-studio-2022-support-for-net-development) page for details on which .NET versions are supported by versions of Visual Studio. Check the [Visual Studio for Mac platform compatibility](/visualstudio/mac/supported-versions-net) page for details on which .NET versions are supported by versions of Visual Studio for Mac. Check the [Mono page for C#](https://www.mono-project.com/docs/about-mono/languages/csharp/) for Mono compatibility with C# versions.
 
@@ -21,9 +21,6 @@ The compiler determines a default based on these rules:
 
 If your project targets a `preview` framework that has a corresponding preview language version, the language version used is the preview language version. You use the latest features with that preview in any environment, without affecting projects that target a released .NET Core version.
 
-> [!IMPORTANT]
-> The new project template for Visual Studio 2017 added a `<LangVersion>latest</LangVersion>` entry to new project files. If you upgrade the target framework for these projects, the `<LangVersion>` setting can [override the default](configure-language-version.md) for the new target framework. Be sure to remove the `<LangVersion>latest</LangVersion>` from your project file to ensure your project uses the recommended compiler version for your target framework. You can update the target framework to access newer language features.
-
 ## C# language version reference
 
 The following table shows all current C# language versions. Older compilers might not understand every value. If you install the latest .NET SDK, you have access to everything listed.
diff --git a/docs/csharp/versioning.md b/docs/csharp/versioning.md
@@ -1,15 +1,22 @@
 ---
 title: Versioning
 description: Understand how versioning works in C# and .NET
-ms.date: 01/08/2017
+ms.date: 09/17/2024
 ms.subservice: advanced-concepts
-ms.assetid: aa8732d7-5cd0-46e1-994a-78017f20d861
 ---
 
 # Versioning in C\#
 
 In this tutorial you'll learn what versioning means in .NET. You'll also learn the factors to consider when versioning your library as well as upgrading to a new version of a library.
 
+## Language version
+
+The C# compiler is part of the .NET SDK. By default, the compiler chooses the C# language version that matches the chosen [TFM](../standard/frameworks.md) for your project. If the SDK version is greater than your chosen framework, the compiler could use a greater language version. You can change the default by setting the `LangVersion` element in your project. You can learn how in our article on [compiler options](language-reference/compiler-options/language.md#langversion).
+
+> [!WARNING]
+>
+> Setting the `LangVersion` element to `latest` is discouraged. The `latest` setting means the installed compiler uses its latest version. That can change from machine to machine, making builds unreliable. In addition, it enables language features that may require runtime or library features not included in the current SDK.
+
 ## Authoring Libraries
 
 As a developer who has created .NET libraries for public use, you've most likely been in situations where you have to roll out new updates. How you go about this process matters a lot as you need to ensure that there's a seamless transition of existing code to the new version of your library. Here are several things to consider when creating a new release:
