Update all sample code to supported .NET Versions - with automation
BillWagner opened this issue · 7 comments
Our sample projects in all repos (docs, docs-desktop, samples, dotnet-api-docs) where current when they were first created. We didn't (and don't) have a systematic process to update all those projects as older versions move out of support.
Our samples cover many scenarios, some of which rely on code built with older versions. We have a number of scenarios we should support:
- Samples that should run on the latest version: This is the most common scenario. In general, our samples should be current. By default, they should specify the latest released version of .NET. (Currently, .NET 5).
- Samples that should run on the most recent LTS version: I haven't identified any in this bucket, but we may have samples that should only be upgraded for new LTS versions.
- Framework 4.8.2: Some of our samples are specific to .NET framework. Where needed, those should stay on the current release of the .NET Framework.
- Samples pinned to a version: Some of our samples are pinned to a specific version. These typically are the "start" samples for a migration scenario. They should not be automatically updated. The automation tool should flag them as possible candidates to update by hand, or remove once we decide migration from a given version is no longer needed.
- Multi-target libraries: Some of our samples use .NET standard 2.0, or support multiple targets. The automation tool should report them for possible by-hand updates. Where possible, we might want to update individual targets for a projects.
It may be that only the first check above can be automated by a tool. If the other scenarios can be identified and reported, we'll learn more about them.
/cc @richlander for visibility
I think most samples should actually specify two versions:
- The minimum version where it worked - if the feature was introduced in 2.0 , it would be 2.0 - regardless whether that version is supported or not.
- The version the sample is built for - this would ideally always be a supported version (unless it's one of the special migration samples)
I think this distinction is important as the "minimum version" tells people where they can expect this to work.
There's also the small problem of changes between versions, where the sample may need to change in small way to support the latest version, in which case the "minimum version" gets weird (the feature worked in 2.0, but this sample won't because of some other thing).
How to do this technically - I would think that defining an MSBuild property in the root for the "current version" and make all the projects use it. Then when we need to change the "current version" something runs the build with the new value and flags all projects which fail to build as to-be-updated-manually. Additional helpers:
- Have a page (.md) which defines the current version and has links to all the SDKs and so on to tell people how to install it
- Specific project's readme.md would point to that page for the "prereqs"
- Have a version.cs file which contains something like "const string CurrentTFM = "net5"" which projects can include if they need to know the current version at runtime (maybe there's a better way to do this - not sure)
Good points @vitek-karas
I am concerned about maintaining buildable samples from the version first introduced. Strategically, that can prevent us from updating sample code to show our latest recommendations based on our latest feature investments. One goal of our sample code is to introduce developers (even those experienced with .NET) to the latest features.
From a practical standpoint, I'm concerned that some of our samples are first written using public preview versions. I don't think it's useful for readers to know which public preview introduced which feature once the GA release has shipped.
For all the samples that are discussed in any of our articles, we do (in text) describe pre-requisites, and include the first version where a feature is available. Even there, we do switch from preview to GA versions once it ships.
I do agree that it the versions should be GA versions (if at all possible). Not sure if this is for other areas but in the samples I've been involved in - we see lot of people finding the sample directly - or sort of unintentionally ignore the docs which refer to it - so having some level of duplication of info in the samples repo feels desirable.
I also understand that this feels like something which will effectively require constant human attention. But maybe it's not such a bad thing to revisit each sample once in cca 1-2 years...
I think the samples should be oriented around the latest version, both to enable people to easily test and run those apps on the latest version, and to demonstrate new features.
Maintaining older versions is challenging, for a few reasons:
- It makes our samples looks stale.
- We'd need to test and document forward-compatibility with newer .NET versions for that app.
- We'd need to tell people to not run the app on the older .NET version because it is no longer serviced/secure.
It's live : https://github.com/dotnet/versionsweeper
I still need to teach the https://github.com/dotnet/versionsweeper tool about .NET Standard, this work is being tracked in dotnet/versionsweeper#5 and would address the last checkbox on this issue.