From 87c649201f7fc6617609487d6a1abb78848d18d1 Mon Sep 17 00:00:00 2001 From: "Tina Schrepfer (LI)" Date: Thu, 5 Sep 2024 16:18:20 -0700 Subject: [PATCH 1/5] Update known issues and breaking changes with latest info and guidance on how we handle breaking changes --- docs/breaking_changes.md | 72 +++++++++++++++++++++++++++++++++++++++- docs/known_issues.md | 4 +-- 2 files changed, 73 insertions(+), 3 deletions(-) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index eefd4e3c..fb293342 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -8,6 +8,45 @@ date: 2024-01-30 We work hard to minimize breaking changes between versions to help minimize disruptions to your extension development, especially as VisualStudio.Extensibility matures. Some breaking changes are necessary, however, in order to add support for new features or in response to user feedback. Those changes are listed here. +# Breaking Changes for Visual Studio 2022 17.12 +The following breaking changes apply to Visual Studio 2022 17.12 + +## VisualStudio.Extensibility + +These breaking changes are associated with VisualStudio.Extensibility. + +### Output Window +User feedback has indicated that the current experience for writing to the Output Window is too complex and confusing. Among the issues we’ve identified are: +- Confusion as to why a resource dictionary is necessary to create and write to an output channel +- Confusion over the requirement that channels have a unique ID, and what those IDs should be +- Unclear naming of functions and objects (window vs. channel, create vs. get) + +To improve the streamline the experience, we have redesigned the API. Documentation of new API is pending. + +You are impacted if you create or write to an output channel in your Gladstone commands. Indicators would be: +- References to Microsoft.VisualStudio.Extensibility.Documents.OutputWindow +- Calls to create a channel, like await Extensibility.Views().Output.GetChannelAsync(…) + +# Breaking Changes for Visual Studio 2022 17.11 + +The following breaking changes apply to Visual Studio 2022 17.10. + +## VisualStudio.Extensibility + +These breaking changes are associated with VisualStudio.Extensibility. + +### Project Query + +The following methods have been marked as [Obsolete] for future removal: + +Microsoft.VisualStudio.ProjectSystem.Query.UpdateExtensions.SetBuildPropertyValue(this IAsyncUpdatable configurations, string name, string value, string storageType) + +Microsoft.VisualStudio.ProjectSystem.Query.UpdateExtensions.Delete(this IAsyncUpdatable buildProperties) + +Microsoft.VisualStudio.ProjectSystem.Query.ProjectConfigurationPropertiesFilterExtensions.BuildPropertiesByName(this IProjectConfigurationSnapshot projectConfiguration, string storageType, params string[] buildPropertyNames) + +While this is *not* a breaking change, information has been added for future reference. + # Breaking Changes for Visual Studio 2022 17.10 The following breaking changes apply to Visual Studio 2022 17.10. @@ -106,4 +145,35 @@ All you need to do for out-of-process extensions is to update the package refere In order to better support creating VSIX packages for your extensions, we've made some changes to the layout of VSSDK-compatible extension projects. The simplest thing to do would be to create a new in-process extension project, which will have the correct behavior. -Make sure you've updated to the latest Visual Studio 2022 17.9+ version and create a new in-process project, called "VisualStudio.Extensibility Extension with VSSDK Compatibility" in the New Project dialog. Copy your extension code into the new project and fix any compilation errors associated with the updated package references. Once you've rebuilt, your manifest file should have the correct value set automatically. \ No newline at end of file +Make sure you've updated to the latest Visual Studio 2022 17.9+ version and create a new in-process project, called "VisualStudio.Extensibility Extension with VSSDK Compatibility" in the New Project dialog. Copy your extension code into the new project and fix any compilation errors associated with the updated package references. Once you've rebuilt, your manifest file should have the correct value set automatically. + +# Guidance and Expectations Around Breaking Changes + +As VisualStudio.Extensibility matures and we continue to attract new users and extension authors, we want to ensure that we have a customer-focused approach to breaking changes that is consistent across the various feature areas in the SDK. Since one of the principals of VisualStudio.Extensibility is to create easy to use APIs that can be sustained over time, it will take us some back and forth iteration to get some of the APIs down to a state that we're satisfied with. Our goal is to provide extenders with the most up to date APIs to unblock scenarios in their extension, but we also want to reserve some room where our engineers can iterate on the shape of the API as we get feedback from customers. In order to achieve both, we have established the following guidance on how we approach how and when we break APIs for VisualStudio.Extensibility. + +## Experimental APIs + +Beginning with our 17.9 release, we introduced the concept of Experimental APIs to extenders. You can find a full description of our approach in the [Experimental APIs doc](https://github.com/microsoft/VSExtensibility/blob/main/docs/experimental_apis.md) on our public GitHub repo, but at a high level, we have marked certain VisualStudio.Extensibility types and members with the [Experimental] attribute to signal to extension authors that we expect those APIs to be less stable across releases than those in the rest of the SDK. + +Typically, we mark APIs as experimental if they are part of a feature area that is still under active development, or if they have been identified through user feedback as requiring usability enhancements. To prevent surprise, extenders who want to use experimental APIs need to proactively disable the associated build error to opt-into using the feature despite the higher likelihood of breaking changes. + +One of the more common questions we get from extenders is about when experimental APIs in VisualStudio.Extensibility will GA, because in most cases they want to make sure their effort migrating existing extensions or writing new ones won’t be interrupted by churn and breaking changes. By using experimental APIs, we can assure extenders that the vast majority of VisualStudio.Extensibility is already essentially GA quality and is as free from unnecessary churn as VSSDK. + +### Breaking Changes to Experimental APIs + +For experimental APIs: +- Breaking changes can be made as part of LTSC minor version releases of Visual Studio. + - A list of breaking changes for the release will be shared by Preview 2 of the release. + - This list will be shared in the Breaking Changes doc in a section labeled explicitly for changes to stable APIs. + - If upcoming changes are known ahead of time, they can be listed in a special section of the Breaking Changes doc for upcoming changes. +- For removing APIs, we may choose to formally deprecate by marking the type or with the [Obsolete] attribute. + - Like with breaking changes, any deprecated APIs may be marked as [Obsolete] by Preview 2 of the release in which they’ll be removed. + +## Stable APIs + +With stable APIs, we want to replicate the stability expectations associated with VSSDK: +- Breaking changes to both VisualStudio.Extensibility APIs and RPC contracts can only be made as part of a major version release of Visual Studio. + - A list of breaking changes must be available by Preview 1 of the release. +- Any removal of APIs or demotion will be done formally through marking the type or with the [Obsolete] attribute. +- Demotion of stable APIs to experimental is considered a breaking change and will be announced. + diff --git a/docs/known_issues.md b/docs/known_issues.md index 45736c7a..d5d8602e 100644 --- a/docs/known_issues.md +++ b/docs/known_issues.md @@ -22,6 +22,6 @@ With Visual Studio 2022 17.9, we've added the ability to publish VisualStudio.Ex We've discovered that if you have a Language Pack installed with Visual Studio, hot-loading new extensions won't work. Instead, until we release a fix, you'll need to close and restart Visual Studio after installing your extensions like you would for traditional non-VisualStudio.Extensibility extensions. -**A fix for this issue has been found and will be available with a future release.** +**This issue is now fixed with Visual Studio 17.11 release.** -*Last updated on 29-May-2024* \ No newline at end of file +*Last updated on 05-September-2024* \ No newline at end of file From e280689e28a98d3a0720fafc771f007fa8ca4d42 Mon Sep 17 00:00:00 2001 From: "Tina Schrepfer (LI)" Date: Thu, 5 Sep 2024 16:31:17 -0700 Subject: [PATCH 2/5] Format additional content as code --- docs/breaking_changes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index fb293342..53822ce9 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -24,8 +24,8 @@ User feedback has indicated that the current experience for writing to the Outpu To improve the streamline the experience, we have redesigned the API. Documentation of new API is pending. You are impacted if you create or write to an output channel in your Gladstone commands. Indicators would be: -- References to Microsoft.VisualStudio.Extensibility.Documents.OutputWindow -- Calls to create a channel, like await Extensibility.Views().Output.GetChannelAsync(…) +- References to Microsoft.VisualStudio.Extensibility.Documents.OutputWindow +- Calls to create a channel, like await Extensibility.Views().Output.GetChannelAsync(…) # Breaking Changes for Visual Studio 2022 17.11 From 27c332e3ce926bf43859090614b18e7c752e5bf8 Mon Sep 17 00:00:00 2001 From: "Tina Schrepfer (LI)" Date: Mon, 9 Sep 2024 11:00:04 -0700 Subject: [PATCH 3/5] Added text in the beginning of breaking changes to point to policy --- docs/breaking_changes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 53822ce9..421d21fc 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -8,6 +8,8 @@ date: 2024-01-30 We work hard to minimize breaking changes between versions to help minimize disruptions to your extension development, especially as VisualStudio.Extensibility matures. Some breaking changes are necessary, however, in order to add support for new features or in response to user feedback. Those changes are listed here. +For more information how our policy and guidance towards breaking changes, please review [here](#Guidance-and-Expectations-Around-Breaking-Changes). + # Breaking Changes for Visual Studio 2022 17.12 The following breaking changes apply to Visual Studio 2022 17.12 From a0ff9c6f27383e22e9c6f9434e4be2e828b6498e Mon Sep 17 00:00:00 2001 From: "Tina Schrepfer (LI)" Date: Mon, 9 Sep 2024 11:41:24 -0700 Subject: [PATCH 4/5] Updated known issues for arm64 issue --- docs/known_issues.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/known_issues.md b/docs/known_issues.md index d5d8602e..92276798 100644 --- a/docs/known_issues.md +++ b/docs/known_issues.md @@ -12,9 +12,9 @@ This is a list of known issues with VisualStudio.Extensibility. We'll keep this We've found a bug that prevents fully out-of-process VisualStudio.Extensibility extensions from installing on ARM64 systems. In the meantime, you could structure your extension as an [in-proc/VSSDK-compatible extension](https://learn.microsoft.com/visualstudio/extensibility/visualstudio.extensibility/get-started/in-proc-extensions) if you need ARM64 compatability. -We will share updates on a fix once we have one available. +**A fix for this issue will soon be available in an upcoming Visual Studio release.** -*Last updated on 29-May-2024* +*Last updated on 09-September-2024* ## Hot-loading issue when language packs are installed From 82c61ce63439d056161fc87aeb33be57b9e2cc4a Mon Sep 17 00:00:00 2001 From: "Tina Schrepfer (LI)" Date: Tue, 10 Sep 2024 09:47:47 -0700 Subject: [PATCH 5/5] Correct typo --- docs/breaking_changes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 421d21fc..9253d293 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -11,7 +11,7 @@ We work hard to minimize breaking changes between versions to help minimize disr For more information how our policy and guidance towards breaking changes, please review [here](#Guidance-and-Expectations-Around-Breaking-Changes). # Breaking Changes for Visual Studio 2022 17.12 -The following breaking changes apply to Visual Studio 2022 17.12 +The following breaking changes apply to Visual Studio 2022 17.12. ## VisualStudio.Extensibility @@ -31,7 +31,7 @@ You are impacted if you create or write to an output channel in your Gladstone c # Breaking Changes for Visual Studio 2022 17.11 -The following breaking changes apply to Visual Studio 2022 17.10. +The following breaking changes apply to Visual Studio 2022 17.11. ## VisualStudio.Extensibility