Add documentation to repo about which platforms this SDK supports (#2046

)

fixes #2032

.github/ISSUE_TEMPLATE/bug_report.md

@@ -31,6 +31,8 @@ Please follow the instructions and template below to save us time requesting add
 
 Below is a generic bug report format. We recommend you use it as a template and replace the information below each header with your own. 
 
+Note that bugs that only affect unsupported platforms will likely be treated as feature requests, and may be closed as "won't fix" if we have no plans to support that platform. See [this document](../../supported_platforms.md) for details on which platforms are officially supported.
+
 ------------------------------- delete above -------------------------------
 
 

.github/ISSUE_TEMPLATE/feature_request.md

@@ -26,6 +26,8 @@ Thank you for raising a feature request! To get started, here's a few things to
 
 As an open source project, we welcome PRs for new features, and we don't want to reject any hard work you've done to contribute. **So propose your solution through an issue first** so we can discuss the changes, and if things look good we will ask you submit a PR to implement the changes.
 
+Note that feature requests that only affect unsupported platforms may be closed as "won't fix" if we have no plans to support that platform. See [this document](../../supported_platforms.md) for details on which platforms are officially supported.
+
 ------------------------------- delete above -------------------------------
 
 **Is your feature request related to a problem? Please describe.**

readme.md

@@ -63,27 +63,9 @@ If you would like to build or change the SDK source code, please follow the [dev
 
 ## OS platforms and hardware compatibility
 
-> .NET Standard 1.3 (IoT Hub SDKs only) is last supported in the [2020-02-27](https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/2020-2-27) and in the [2020-1-31 LTS](https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/lts_2020-1-31) releases.
+For an official list of all the operating systems and .NET platforms that we support, please see [this document](./supported_platforms.md)
 
-The IoT Hub device SDK for .NET can be used with a broad range of device platforms and is officially supported on the following Operating Systems:
-
-*  Windows versions officially supported by Microsoft.
-*  [Linux distributions](https://docs.microsoft.com/en-us/dotnet/core/install/linux) supported by .NET core.
-
-> Note: For Linux, we test our clients against Ubuntu 16.04.7 LTS.
-
-The NuGet packages provide support for the following .NET flavors:
-- .NET Standard 2.1
-- .NET Standard 2.0
-- .NET Framework 4.7.2 (IoT Hub SDKs only)
-- .NET Framework 4.5.1 (IoT Hub SDKs only)
-
-For details on .NET support see the [.NET Standard documentation](https://docs.microsoft.com/dotnet/standard/net-standard).
-For details on OS support see the following resources:
-
-- [.NET Core Runtime ID Catalog](https://docs.microsoft.com/dotnet/core/rid-catalog)
-- [.NET Framework System Requirements](https://docs.microsoft.com/dotnet/framework/get-started/system-requirements)
-- [Configure TLS Protocol Version and Ciphers](./configure_tls_protocol_version_and_ciphers.md)
+Note that you can configure your TLS protocol version and ciphers by following [this document](./configure_tls_protocol_version_and_ciphers.md)
 
 ## Key features and roadmap
 

supported_platforms.md

@@ -0,0 +1,57 @@
+# Microsoft Azure IoT SDKs for .NET
+
+This SDK is tested nightly on a mix of .NET implementations on both Windows 10 and on Ubuntu 1604. For additional details
+for each tested platform, see the respective sections below. 
+
+## Supported .NET versions
+
+The NuGet packages provide support for the following .NET versions:
+- .NET Standard 2.1
+- .NET Standard 2.0
+- .NET Framework 4.7.2 (IoT Hub SDKs only)
+- .NET Framework 4.5.1 (IoT Hub SDKs only)
+
+This SDK _may_ work with newer versions of .NET, but there are no guarantees that they will _always_ work for those until we officially add support for them.
+versions nor are there guarantees that we will fix bugs that are only present on those versions.
+
+Note that applications will resolve the dll that is being referenced based on the framework precedence rules. This means that .NET Framework targeting applications will look for the closet .NET Framework dll. In the absence of that, it will pick up the closest .NET Standard dll. Similarly for netcoreapp applications will look for the closest netcoreapp dll and in the absence of one will pick the closest .NET Standard dll. Since we publish the above list of dlls, you should target the appropriate net target to ensure you get the desired .NET API coverage
+
+## Windows 10
+
+Note that, while we only directly test on Windows 10, we do support other Windows versions officially supported by Microsoft.
+
+Nightly test platform details:
+
+.NET versions tested on
+- .NET Core 3.1
+- .NET Core 2.1.18
+- .NET Framework 4.7.2 (only IoT Hub SDKs tested)
+- .NET Framework 4.5.1 (only IoT Hub SDKs tested)
+
+
+Default locale: en_US, platform encoding: Cp1252
+
+OS name: "windows server 2016", version: "10.0", arch: "amd64", family: "windows"
+
+## Ubuntu 1604
+
+Note that, while we only directly test on Ubuntu 1604, we do generally support other [Linux distributions supported by .NET core](https://docs.microsoft.com/en-us/dotnet/core/install/linux). 
+
+Nightly test platform details:
+
+.NET versions tested on:
+- .NET Core 3.1
+- .NET Core 2.1.18
+
+Default locale: en_US, platform encoding: UTF-8
+
+OS name: "linux", version: "4.15.0-1113-azure", arch: "amd64", family: "unix"
+
+## Miscellaneous support notes
+
+- This library has a [preview version](https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/preview_2021-6-8) that supports .NET 5.0, but we don't officially support it in our main releases yet.
+- This library does not officially support being run on MacOS.
+- This library does not officially support being run in Xamarin applications.
+- .NET Standard 1.3 (IoT Hub SDKs only) is last supported in the [2020-02-27](https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/2020-2-27) and in the [2020-1-31 LTS](https://github.com/Azure/azure-iot-sdk-csharp/releases/tag/lts_2020-1-31) releases.
+- [.NET Core Runtime ID Catalog](https://docs.microsoft.com/dotnet/core/rid-catalog)
+- In order to run this SDK your device will need to meet the [.NET Framework System Requirements](https://docs.microsoft.com/dotnet/framework/get-started/system-requirements)

vsts/vsts.yaml

@@ -32,6 +32,7 @@ jobs:
 
     condition: succeeded()
     pool:
+      # If this is changed, don't forget to update supported_platforms.md in the root directory. That document outlines what OS we test on and should stay up to date.
       name: Hosted Ubuntu 1604
     steps:
       - task: Docker@1
@@ -141,6 +142,7 @@ jobs:
 
     condition: succeeded()
     pool:
+      # If this is changed, don't forget to update supported_platforms.md in the root directory. That document outlines what OS we test on and should stay up to date.
       name: Hosted VS2017
     steps:
       - script: |