Docs: Samples Directory needs to separate build environments

[BillWagner]

We discovered this while working on PR #870

A few of our samples require the full framework. That's fine, because they cover migrating from the full framework to Core, or supporting both (see here: https://docs.microsoft.com/en-us/dotnet/articles/core/porting/project-structure)

We need a project structure that enables the CI build server to build the right set of samples in the correct configuration. This is a matrix that comprises .NET products (.NET Core, .NET Standard, Full .NET Framework), and platforms (Windows, Linux, MacOS). Some Core projects may have a native dependency, because they explain how to create those kinds of projects.

This structure is further complicated by our current structure, which organizes samples based on content: C# samples, F# samples, .NET Core samples, and so on.

I believe all language samples (C# and F#) should build on all platforms. @cartermp can verify for F#. (I will verify for C#).

Core samples probably should all build on all supported Core platforms.

The interesting ones now are those that discuss the full .NET framework, or how to migrate from the full framework to Core. They are listed at the end of this issue.

Proposal

We'll make a new directory for samples that are meant to build on the full framework only. This should be /samples/full-framework. This will include any code that discusses migration to core, or supporting the full framework as a development environment.

In the future, we can add sub-directories for other environments when this repository adds samples specific to those environments (for example, Xamarin projects, Windows client frameworks, and so on).

Samples Affected

Samples that do not build on Ubuntu (by design) are:

/samples/core-projects/libraries/frameworks-library
/samples/core-projects/libraries/migrate-library
/samples/core-projects/libraries/migrate-library-pcl
/samples/core-projects/libraries/migrate-library-xproj
/samples/core-projects/libraries/migrate-library-xproj-keep-csproj

These should all move to the new /samples/full-framework directory.

The topics that reference those samples must have all links updated when the samples move.

[dend]

That makes sense. From a CI standpoint, I want different build agents to cover different areas, with certainty that the areas covered are not failing because of a framework scope mismatch.

/samples/full-framework makes sense to me.

[richlander]

A simple convention makes sense.

"full-framework" is a colloquialism, so we should pick something different than that. One option is to use the NuGet names. This will also help with specifying target framework version. So, a .NET Framework 4.6 project would be "net46". See: https://docs.nuget.org/Create/TargetFrameworks.

[dend]

@richlander we need something that can fully encompass all possible variations of .NET "full" framework. Within full-framework we can create sub-directories with net46 and so on (because what will happen when net47 comes out?).

That said, we also need to move all core samples to /samples/core-framework or /samples/dotnet-core - easier to manage and more intuitive.

[BillWagner]

As I think about it, I really like the idea of using the NuGet package names.

Consider that we have CI servers with known configurations. For example, Windows with .NET Core 1.0, Windows with .NET 46, Ubuntu with .NET Core 1.0.

Each CI Server builds all samples it can:
. Windows with .NET Core 1.0: all samples for .NET Core 1.0
. Windows with .NET 46: all samples for .NET 46, or earlier, and all .NET Core 1.0 samples.
. Ubuntu with .NET Core 1.0: all samples for .NET Core 1.0

When .NET 47 comes out, we have two choices:

1. Add a Windows with 47 config (in addition to 46). The new server builds all 47 and earlier samples.
2. Update all 46 samples (and the build server) to 47.

Either would work, and we can do either as business needs dictate.

[mairaw]

I think we should call it netframework or something like that. I don't think we want to keep changing folders every time a new version comes out.

[dend]

@BillWagner something to keep in mind is that there will be a matrix, where we can say: _this sample runs on 4.5, 4.6 but not earlier_ - that means that a single machine (e.g. Windows 7 with .NET 4.6) will attempt to build all samples within the scope (/samples/netframework - following @mairaw's naming convention here) and then report back whether it was successful or not. Besides, some samples will be spanning framework versions, so we need to validate that as well.

Thoughts on the above?

[richlander]

I think there are two good models:

• Match the guide name.
• Match the NuGet short name (no version).

If we look at Xamarin, it won't just be Xamarin, but Xamarin Android and Xamarin iOS (and others). If we keep that in mind, then the NuGet name is the best, IMO.

[dend]

In the Xamarin case, would it make sense to have the structure similar to /samples/xamarin/android then?

[richlander]

That would work.

I would then use "framework" for .NET Framework to match "core" for .NET Core.

[BillWagner]

Updated Proposal

We need to solve the immediate problem of building samples for all platforms where we currently have code. The solution should provide a path for future concerns such as:

• Xamarin Builds (build iOS and Android)
• Versions of the framework or core, for upgrade scenarios
• Native interop samples that (by definition) are valid only on one supported platform.

Currently we have:

samples/core-projects
samples/csharp-language
samples/getting-started
samples/linq

We will move to a system with:

/samples/core: Builds on all supported core platforms. (Note this means that standalone package builds must contain a runtime node for each of win64, ubuntu, and MacOS)
/samples/framework: Builds on the .NET Framework (currently 4.6)
/samples/csharp: builds on all supported core platforms.
/samples/fsharp: builds on all supported core platorms. (This is currently a placeholder).

This can be extended in the future as new platforms are needed. For example:

• /samples/xamarin-ios
• /samples/xamarin-android

Version Specific Samples

In the future, when we add new samples that are version dependent, we can create version-specific sub-folders underneath the proposed top-level folders. These version specific folders would use the NuGet names for the framework and version.

Moving current samples

There are two top-level folders currently containing samples that need to move to accommodate this new proposal.

• /samples/getting-started
  
  
  
  • This directory contains 2 getting started projects: one for C#, and one for core. I propose moving 'getting-started' under each main topic (for example samples/csharp/getting-started and samples/core/getting-started) As we add more different environments, customers will be trying to get started with one of those, rather than getting started with everything .NET. Separating the getting started content for each major platform would make it easier for beginners to find the samples they need.
  
  
• /samples/linq
  
  
  
  • These should move under /samples/core/linq. The LINQ samples have all been updated to run on Core. This decision implies that any sample that runs on core would also run on framework. I propose we assume that, until we find a counter-example.
  
  

Please vote via :+1: or :-1: emoji. If further discussion is required, please comment.
/cc @mairaw @richlander @dend

[dend]

@BillWagner what about /samples/xamarin/ios - overall the proposal looks good, but also would be great to establish some guidelines of how this will be extended in the future so that we are not really splitting the experience.

[mairaw]

I like the proposal too. Agree with @dend's comment as well.

[BillWagner]

Self-assigning, and PR coming.

I'll put guidance in the contributing.md file about extending in the future.

[BillWagner]

fixed in #890