One pager writeups

documentation/specs/proposed/decoupling-vs-sdk.md

@@ -0,0 +1,40 @@
+# Decoupling VS builds of .NET SDK projects
+The experience of building a .NET SDK project can differ significantly depending if the project was built using Visla Studio / MSBuild or `dotnet build`. The build can produce different diagnostics, use different language rules, etc... and that is because building a .NET SDK project from Visual Studio mixes components from MSBuild and the .NET SDK. This means core tooling, like the compiler, can be substantially different between the two types of build. This leads to customer confusion and hard to diagnose problems, as well as increased code workload. To solve this want to ensure that when building a .NET SDK project we use the components from the .NET SDK to do so.
+
+## Goals and Motivation
+
+We are aiming for:
+ - Consistent end-user eperience for build in either DotNet CLI or Visual Studio.
+ - Decoupling the .NET SDK experience from Visual Studio 
+ - Decoupling the .NET SDK from VS.
+
+The reason we are persuing this is for a better experience when using or writting Roslyn analyzers and MSBuild Tasks. Currently tooling authors need to target NetStandard2.0 for their projects to be recognized by VS. Another options is to multi-target but it takes a lot more effort and time spent on that. Another aspect is the user experience, if the Roslyn version for VS analyzers and generators doesn't match the one in Visual Studio, they do not work.
+
+## Impact
+There are a few area of impact:
+ - .NET SDK style project builds will be more stable between VS and CLI builds, as the tooling will not be devided between different versions.
+ - Reduced cost of development for external and internal teams that contribute to Roslyn Analyzers, SourceBuild generators, or MSBuild Tasks.
+ - End-user will not experience mismatch between analyzer versions, and confirmation that their .NET SDK style builds will behave the same way in VS and in the command line.
+
+## Stakeholders
+For the internal stakeholder, we have the teams that will continue the work to fully complete the VS and .NET SDK decoupling feature after our base work is done. There are two handovers in this project:
+
+1. Enabling the MSBuild.exe execution state to be the same as DotNet command line invocation so the Roslyn team can enable the use of their core compiler in VS.
+2. Tasks and other projects can be written in .NET Core and the .NET SDK projects will build successuflly in VS. This enables other teams to migrate their tasks to .NET Core instead of keeping them targeting .NET Framework.
+
+The handovers should allow other teams to proceed with their work smoothly and no change in build behaviour should be present within MSBuild.
+
+## Risks
+A few risks associated with this feature:
+ - Our work is early in the development effort. If this feature is discovered to have too large of an impact in experience of performance the work might be delayed or discarded.
+ - There might be a performance hit on VS once we start running tasks on .NET Core. It would depending on the amount of non-framwork tasks that the project will need to load when opening it in VS. The performance gain from pre-loading will not be available in this scenario.
+ - There are no concrete deadlines for our part of the feature, but we are aiming for an early preview cycle, so we have a chance to measure the consequences and fix any issues that arise.
+
+## Plan
+ 1. Ensure that MSBuild.exe provides the same execution state as the dotnet command line invocation.
+    -  This is should take around 1 dev week to complete, and will be handed over to Roslyn team.
+ 2. Implement .NET Core task host, tasks can be executed on the .NET Core vresion instead of .NET framework.
+    - This should take 1 to 2 dev months to complete, including extensive testing. This would be handed over to internal teams that have custom tasks so they can be updated and tested.
+ 3. Load common targets from the .NET SDK and not from .NET NetFramework on VS. This work depends on other team's finilizing their part of the feature and might not be in scope for .NET 10.
+    - This should take a dev week, if there are no major bugs or regressions.
+

documentation/specs/proposed/evaluation-perf.md

@@ -0,0 +1,24 @@
+# Evaluation performance investigations
+In the current effort to improve performance of MSBuild, we ideantified the evaluation as one of the focus areas of this effort. Evalution is the ifrst step when building, and it determines references, how projects are connected and what needs to be build. Because of this it runs in every single build, be it Design-time builds in Visual Studio, up-to-date builds or full builds.
+
+## Description
+Current performance state of evaluation is mostly unkown, as it is not measured in any ways by the team. As such, we are unsure which specific areas can be improve. The investigation about this is necessary so we can identify weaknesses, and possible fixes.
+
+ - We could do profiling
+ - Jit compilation of MSBuild itself. 
+ - We could cache at eval
+
+ Constraint - needs to work as it does today, but fast. We can break some edge cases.
+
+## Goals and Motivation
+We are trying to make evaluation phase of the build more performant, since it is almost always executed any performance gain becomes noticeable. A performant evaluation phase would decrease build times in general, in CI cases it frees up resources, and in individual cases it can increase dev-loop performance by making up-to-date and incremental builds go faster.
+
+In this moment we are still in investigation phase, the obejective is to add code markers, so we can idetentify low hanging fixes, and improvement areas when testing builds within PerfStar.
+
+## Risks
+One of the big risks is accidentally changing the current behaviour of evaluation. One of the constraints of improvement is that evaluation has the same behavior, with the exception of edge cases where we can sometimes change it.
+
+## Plan
+The plan for evaluation at the moment is to add more code markers during execution so we can use PerfStar to have a detailed view of how long each part of evaluation phase takes.
+
+Larger changes to the evaluation are possible and under consideration for future iterations, like trying to cache the evaluation result in MSBuild. However we are focusing on investigation and performance gains with less work at the moment.

documentation/specs/proposed/perfStar.md

@@ -0,0 +1,38 @@
+# PerfStar
+PerfStar is a performance tracking and investigation tool for MSBuild. PerfStar infrastructure captures performance measurements of main MSBuild branch on schedule and allows us to request experimental runs and collect performance of the new changes. The first version of this project is being finalized, with some fixes necessary to run it automatically and according to prerequisites.
+
+## Goals and Motivation
+MSBuild currently does not have a lot of performance data outside of Visual Studio performance tracking, which has a lot of variables that are beyond the team's control. PerfStar enables us to measure our performance without interference of elements that the team does not own. As such, we can measure the performance of in-development features and how it will impact build times, as well as have concrete numbers when working on performance improvement tasks.
+
+## Impact
+Perfstar's impact is focused on the team. We will be able to track performance with concrete numbers. Because of that the team will be able to take more informed decisions about taking performance improvement work, as well as future and implementation of new features.
+
+## Risks
+The risks associated with our dependencies is about Crank, which is owned by the ASP.NET team and we use it to help us with machine setup to run the performance tests. 
+
+## Plan
+Investiment for .NET 10:
+ 1. Making PerfStar execute automatically the way the design doc indicates
+    - Around 1 dev week.
+2. The PowerBI reporting is working and updating the new information
+   - Around 2 dev weeks.
+3. New performance tests for new features, and writting docs on how to write those tests. Next feature planned for tests: BuildCheck.
+   - Around 3 dev days per feature.
+4. Analyze stability of performance tests, and fix any noise found. This will be done through multiple iterations of the same test in the same machine, as well as updating the PowerBI report to handle the new data.
+   - Around 2 dev weeks.
+5. Add more tests using `msbuild.exe` for build instead of `dotnet build`.
+   - Around 1 dev week.
+6. Timeboxed collection of feedback from our team, as well as performance investigations that can derive from those.
+   - 1 - 2 dev month depending on feedback and requests for improvement from the team.
+7. Add more test cases. For example, build time with different verbosity levels.
+   - Around 1 dev week.
+
+There are more improvements form PerfStar, but these are not established for .NET 10 yet as they depend on the team's feedback to PerfStar.
+1. Add more measurements, like dotnet counter tool.
+   - Around 3 dev weeks.
+2. Trace collection when specific features are turned on for the test.
+   - Around 2 - 3 dev weeks.
+3. Report improvements:
+   - Compare performance numbers between two different iterations that are not from `main` branch. Around 2 dev weeks.
+   - Automatic detection of performance issues, so we don't need to check the reports to see regressions. Around 1 dev month.
+   - Run MSBuild API tests, so we can check performance of calls relating to Visual Studio builds. Around 1 dev month.