Publish managed language strategy (dotnet#33867)

* Publish managed language strategy

Publish the strategy statements for all three languages in the .NET Fundamentals section.

In addition, publish the annotated strategy statements in each of the corresponding language guide.

* fix build issues

* add extension for link.

* Update docs/csharp/tour-of-csharp/strategy.md

Co-authored-by: David Pine <[email protected]>

---------

Co-authored-by: David Pine <[email protected]>

docs/csharp/index.yml

@@ -81,6 +81,8 @@ landingContent:
     linkLists:
       - linkListType: overview
         links:
+          - text: C# language strategy
+            url: ./tour-of-csharp/strategy.md
           - text: "Programming concepts"
             url: ./programming-guide/concepts/index.md
       - linkListType: quickstart

docs/csharp/toc.yml

@@ -11,6 +11,8 @@ items:
     href: tour-of-csharp/program-building-blocks.md
   - name: Major language areas
     href: tour-of-csharp/features.md
+  - name: C# language strategy
+    href: tour-of-csharp/strategy.md
   - name: Tutorials
     items:
     - name: Choose your first lesson

docs/csharp/tour-of-csharp/strategy.md

@@ -0,0 +1,32 @@
+---
+title: C# language strategy
+description: We will keep evolving C# to meet the changing needs of developers and remain a state-of-the-art programming language. We will innovate eagerly and broadly in collaboration with C# developers
+ms.date: 02/06/2023
+---
+# Annotated C# strategy
+
+[!INCLUDE [csharp](../../../includes/csharp-strategy.md)]
+
+## How strategy guides C\#
+
+The C# strategy guides our decisions about C# evolution, and these annotations provide insight into how we think about key statements.
+
+> "we will innovate eagerly and broadly"
+
+The C# community continues to grow, and the C# language continues to evolve to meet the community's needs and expectations. We draw inspiration from a variety of sources to select features that benefit a large segment of C# developers, and that provide consistent improvements in productivity, readability, and performance.
+
+> "being careful to stay within the spirit of the language"
+
+We evaluate new ideas in the spirit and history of the C# language. We prioritize innovations that make sense to the majority of existing C# developers.
+
+> "improvements that benefit all or most developers"
+
+Developers use C# in all .NET workloads, such as web front and back ends, cloud native development, desktop development and building cross platform applications. We focus on new features that have the most impact either directly, or by empowering improvements to common libraries. Language feature development includes integration into our developer tools and learning resources.
+
+> "high commitment to backwards compatibility"
+
+We respect that there is a massive amount of C# code in use today. Any potential breaking change is carefully considered against the scale and impact of disruption to the C# community.
+
+> "maintaining stewardship"
+
+[C# language design](https://github.com/dotnet/csharplang/tree/main/meetings) takes place in the open with community participation. Anyone can propose new C# features in our [GitHub repos](https://github.com/dotnet/csharplang). The [Language Design Team](https://github.com/orgs/dotnet/teams/ldm) makes the final decisions after weighing community input.

docs/fsharp/index.yml

@@ -18,6 +18,8 @@ landingContent:
         links:
           - text: "What is F#?"
             url: what-is-fsharp.md
+          - text: "F# strategy"
+            url: strategy.md
           - text: "First steps in F#"
             url: /training/modules/fsharp-first-steps/
           - text: "Install F#"

docs/fsharp/strategy.md

@@ -0,0 +1,28 @@
+---
+title: F# language strategy
+description: We will drive F# evolution and support the F# ecosystem with language leadership and governance. We will encourage community contributions to improve the F# language and developer experience.
+ms.date: 02/06/2023
+---
+# Annotated F# strategy
+
+[!INCLUDE [Fsharp](../../includes/fsharp-strategy.md)]
+
+## How strategy guides F\#
+
+The F# strategy guides our decisions about F# evolution, and these annotations provide insight into how we think about key statements.
+
+> "support the F# ecosystem with language leadership and governance"
+
+The F# community makes significant contributions to F#. We support this by doing almost all technical decision making via GitHub and holding public compiler design sessions. We also provide architectural direction and aid users wishing to contribute. F# is delivered as part of the .NET SDK.
+
+> "rely on community to provide important libraries, developer tools and workload support"
+
+The F# community provides many libraries and tools that solve a variety of developer challenges. Offerings include libraries for .NET front end applications and JavaScript transpilers that enable you to write full stack applications in F#. The community also provides developer tools for editing, code formatting, and linting.
+
+> "F# will support .NET platform improvements and maintain interoperability with new C# features"
+
+We know F# developers want to use the latest .NET features and that many projects and programmers embrace both F# and C#. We evolve F# to work well with C# and take advantage of new .NET runtime and library improvements.
+
+> "lower the barrier to entry into F# for new developers and organizations"
+
+Simplifying F# makes it easier for new developers to learn and for experienced programmers to get their job done. Improving the approachability of F# includes ongoing efforts to rephrase error messages and simplifying language features.

docs/fsharp/toc.yml

@@ -3,6 +3,8 @@ items:
   href: index.yml
 - name: What is F#
   href: what-is-fsharp.md
+- name: F# language strategy
+  href: strategy.md
 - name: Get started
   href: get-started/index.md
   items:

docs/fundamentals/index.yml

@@ -25,6 +25,8 @@ landingContent:
             url: https://dotnet.microsoft.com/learn/dotnet/what-is-dotnet
           - text: Introduction to .NET
             url: ../core/introduction.md
+          - text: .NET languages
+            url: ../fundamentals/languages.md
       - linkListType: concept
         links:
           - text: .NET Standard

docs/fundamentals/languages.md

@@ -0,0 +1,41 @@
+---
+title: .NET Managed languages strategy
+description: Each .NET language is unique. C# is the most widely used language and the language most of .NET is written in. F# explores new language possibilities and the community provides a rich experience across platforms. We remain committed to Visual Basic and continue to invest in maintaining C# interop and Visual Studio features for folks that love Visual Basic or want a stable language.
+author: billwagner
+ms.author: wiwagn
+ms.date: 02/06/2023
+ms.topic: conceptual
+---
+# Microsoft .NET language strategy
+
+Microsoft offers 3 languages on the .NET platform – C#, F# and Visual Basic. In this article, you’ll learn about our strategy for each language. Look for links to additional articles on how these strategies guide us and ways to learn more about each language.
+
+## C\#
+
+C# is a cross-platform general purpose language that makes developers productive while writing highly performant code. With millions of developers, C# is the most popular .NET language. C# has broad support in the ecosystem and all .NET [workloads](../standard/glossary.md#workload). Based on object-oriented principles, it incorporates many features from other paradigms, not least functional programming. Low-level features support high-efficiency scenarios without writing unsafe code. Most of the .NET runtime and libraries are written in C#, and advances in C# often benefit all .NET developers.
+
+### Our strategy for C\#
+
+[!INCLUDE [csharp](../../includes/csharp-strategy.md)]
+
+You can read more about how this strategy guides us in the [C# guide](../csharp/tour-of-csharp/strategy.md).
+
+## F\#
+
+F# is a succinct, robust and performant language that is expression-based and immutable by default. It focuses on expressive power, simplicity and elegance and is used by many thousands of developers that appreciate its pragmatic function-first approach to .NET. F# offers the full power of .NET and works well with C# for mixed language solutions. The community makes significant contributions to the compiler and runtime, as well as a broad array of F# tools and frameworks.
+
+### Our strategy for F\#
+
+[!INCLUDE [fsharp](../../includes/fsharp-strategy.md)]
+
+You can read more about how this strategy guides us in the [F# guide](../fsharp/strategy.md).
+
+## Visual Basic
+
+Visual Basic (VB) has a long history as an approachable language favoring clarity over brevity. Its hundreds of thousands of developers are concentrated around the traditional Windows-based client [workloads](../standard/glossary.md#workload) where VB has long pioneered great tooling and ease of use.  Today’s VB developers benefit from a stable and mature object-oriented language paired with a growing .NET ecosystem and ongoing tooling improvements. Some .NET workloads are not supported in VB, and it is common for VB developers to use C# for those scenarios.
+
+### Our strategy for Visual Basic
+
+[!INCLUDE [visual-basic](../../includes/vb-strategy.md)]
+
+You can read more about how this strategy guides us in the [Visual Basic guide](../visual-basic/getting-started/strategy.md).

docs/fundamentals/toc.yml

@@ -59,6 +59,8 @@ items:
   items:
   - name: Introduction to .NET
     href: ../core/introduction.md
+  - name: .NET languages
+    href: ../fundamentals/languages.md
   - name: .NET implementations
     href: ../fundamentals/implementations.md
   - name: .NET class libraries

docs/index.yml

@@ -211,12 +211,16 @@ conceptualContent:
           text: Garbage collection
 
 # tools section (optional)
-## Languages: C#, F#, and Visual Basic
+## Languages: strategy, C#, F#, and Visual Basic
 tools:
   title: Programming languages # < 60 chars (optional)
-  summary: "You can write .NET apps in C#, F#, or Visual Basic."
+  summary: "Write your app in your favorite language"
   items:
     # Card
+    - title: "Write .NET apps in C#, F#, or Visual Basic"
+      imageSrc: /media/logos/logo_net.svg
+      url: fundamentals/languages.md
+    # Card
     - title: "A modern, object-oriented, and type-safe language"
       imageSrc: /media/logos/logo_Csharp.svg
       url: csharp/index.yml

docs/visual-basic/getting-started/strategy.md

@@ -0,0 +1,32 @@
+---
+title: Visual Basic language strategy
+description: We will ensure Visual Basic remains a straightforward and approachable language with a stable design. The core libraries of .NET (such as the BCL) will support VB and many of the improvements to the .NET Runtime and libraries will automatically benefit VB.
+ms.date: 02/06/2023
+---
+# Annotated Visual Basic language strategy
+
+[!INCLUDE [visual-basic](../../../includes/vb-strategy.md)]
+
+## How strategy guides Visual Basic
+
+The Visual Basic strategy guides our decisions about VB evolution, and these annotations provide insight into how we think about key statements.
+
+> "Visual Basic remains a straightforward and approachable language"
+
+Visual Basic’s natural language syntax enables programmers and non-programmers to read code and engage in meaningful discussions. Many people embrace the design of Visual Basic, and we do not plan to change that design.
+
+> "language with a stable design"
+
+The Visual Basic design allows programmers to build solid applications today and to understand code written across a long period of time without stylistic changes.
+
+> "VB will generally adopt a consumption-only approach and avoid new syntax"
+
+New features in the .NET runtime and C# sometimes require language changes to implement. We will maximize interop by supporting many of these features and maximize stability with a consumption only approach. A consumption only approach means Visual Basic code can access .NET APIs and types built on new .NET runtime features, but Visual Basic won’t add syntax to define types that use those features. This allows new features to benefit Visual Basic users with little or no syntax changes.
+
+> "We will continue to invest in the experience in Visual Studio"
+
+We will continue to improve the Visual Studio experience for Visual Basic developers, such as providing analyzers, code fixes and IDE productivity features.
+
+> "in core VB scenarios"
+
+We will focus on existing scenarios supported by VB and do not anticipate adding support for new workloads, such as web front ends or cross-platform UI frameworks

docs/visual-basic/index.yml

@@ -37,6 +37,8 @@ landingContent:
     linkLists:
       - linkListType: overview
         links:
+          - text: Language strategy
+            url:  getting-started/strategy.md
           - text: Programming concepts
             url: programming-guide/concepts/index.md
       - linkListType: whats-new

docs/visual-basic/toc.yml

@@ -1,5 +1,8 @@
+items:
 - name: Visual Basic Guide
   href: index.yml
+- name: Visual Basic strategy
+  href: getting-started/strategy.md
 - name: What's New for Visual Basic
   href: whats-new/index.md
 - name: Breaking changes in the compiler

includes/csharp-strategy.md

@@ -0,0 +1,7 @@
+---
+author: billwagner
+ms.author: wiwagn
+ms.date: 02/05/2023
+ms.topic: include
+---
+We will keep evolving C# to meet the changing needs of developers and remain a state-of-the-art programming language. We will innovate eagerly and broadly in collaboration with the teams responsible for .NET libraries, developer tools, and workload support, while being careful to stay within the spirit of the language. Recognizing the diversity of domains where C# is being used, we will prefer language and performance improvements that benefit all or most developers and maintain a high commitment to backwards compatibility. We will continue to empower the broader .NET ecosystem and grow its role in C#’s future, while maintaining stewardship of design decisions.

includes/fsharp-strategy.md

@@ -0,0 +1,7 @@
+---
+author: billwagner
+ms.author: wiwagn
+ms.date: 02/05/2023
+ms.topic: include
+---
+We will drive F# evolution and support the F# ecosystem with language leadership and governance. We will encourage community contributions to improve the F# language and developer experience. We will continue to rely on the community to provide important libraries, developer tools and [workload](../docs/standard/glossary.md#workload) support. As the language evolves,  F# will support .NET platform improvements and maintain interoperability with new C# features. We will work across language, tooling, and documentation to lower the barrier to entry into F# for new developers and organizations as well as broadening its reach into new domains.

includes/vb-strategy.md

@@ -0,0 +1,7 @@
+---
+author: billwagner
+ms.author: wiwagn
+ms.date: 02/05/2023
+ms.topic: include
+---
+We will ensure Visual Basic remains a straightforward and approachable language with a stable design. The core libraries of .NET (such as the BCL) will support VB and many of the improvements to the .NET Runtime and libraries will automatically benefit VB. When C# or the .NET Runtime introduce new features that would require language support, VB will generally adopt a consumption-only approach and avoid new syntax. We do not plan to extend Visual Basic to new workloads. We will continue to invest in the experience in Visual Studio and interop with C#, especially in core VB scenarios such as Windows Forms and libraries.