From fd0d92d7380ab07ee5147416728ff86b4e22e42f Mon Sep 17 00:00:00 2001 From: KubaD Date: Tue, 15 Oct 2024 14:32:12 +0200 Subject: [PATCH] [S] Documentation signpost added (#4501) * * added new documentation readme page which contains categorized links to all dother documentation pages in this repository with brief description * documentaiton section in repo readme file updated with a link to documentation readme * lint compilation errors fixed * more links to documentation pages added to the signpost --------- Co-authored-by: Kuba Drazka --- README.md | 5 +-- docs/README.md | 42 +++++++++++++++++++ docs/blazor-scenarios.md | 1 + docs/crossgen-scenarios.md | 1 + eng/common/template-guidance.md | 7 ++-- .../GC.Analysis.API/README.md | 2 +- 6 files changed, 50 insertions(+), 8 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index 40c5801db7f..c22791677f6 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,7 @@ Finding these benchmarks in a separate repository might be surprising. Performan ## Documentation -* [Microbenchmarks Guide](./src/benchmarks/micro/README.md) for information on running our microbenchmarks -* [Scenario Tests Guide](./docs/scenarios-workflow.md) for information on running our real-world scenario benchmarks -* [Benchmarking workflow for dotnet/runtime repository](./docs/benchmarking-workflow-dotnet-runtime.md) for information on benchmarking local [dotnet/runtime](https://github.com/dotnet/runtime) builds -* [Profiling workflow for dotnet/runtime repository](./docs/profiling-workflow-dotnet-runtime.md) for information on profiling local [dotnet/runtime](https://github.com/dotnet/runtime) builds +See the [documentation signpost](./docs/readme.md). ## Contributing to Repository diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..b336392ec92 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,42 @@ +# .NET Performance Repository Documentation Readme + +The documentation in this repo is organized into the following sections: + +## Getting Started + +- [Prerequisites](prerequisites.md) - Information on what you need to get started. +- [Perf report walkthrough](perfreport-walkthrough.md) - This document describes Performance Report Advanced Features. +- [Crank to Helix workflow](crank-to-helix-workflow.md) - Information on how to schedule performance tests to be run on Helix machines using Crank (instead of running locally). +- [Profiling workflow dotnet runtime](profiling-workflow-dotnet-runtime.md) - This doc explains how to profile local [dotnet/runtime](https://github.com/dotnet/runtime) builds and it's targetted at [dotnet/runtime](https://github.com/dotnet/runtime) repository contributors. +- [Pipeline templates](../eng/common/template-guidance.md) - Information on azure yml pipelines. + +## Running Benchmarks + +- [BenchmarkDotNet](benchmarkdotnet.md) - Information of how to run benchmarks using BenchmarkDotNet tool and interpret results. +- [Benchmarking workflow](benchmarking-workflow-dotnet-runtime.md) - Information about the (micro)benchmarks for the [dotnet/runtime](https://github.com/dotnet/runtime) in this repository. +- [Microbenchmarks Guide](../src/benchmarks/micro/README.md) for information on running our microbenchmarks. +- [Micro Benchmarks of .NET Runtime(s)](../src/benchmarks/micro/README.md) - Information on benchmarks of .NET Runtime(s). +- [Microbenchmarks design guidelines](microbenchmark-design-guidelines.md) - Detailed guidelines on how to design and write microbenchmarks. +- [benchmarks_local.py script guide](../src/scripts/BENCHMARKS_LOCAL_README.md) - Description of a script for testing the performance of the different dotnet/runtime build types locally. +- [ResultsComparer tool](../src/tools/ResultsComparer/README.md) - Information on tool which allows for easy comparison of provided benchmark results. +- [Serializers Benchmarks](../src/benchmarks/micro/Serializers/README.md) - Information on benchmarks of the most popular serializers. +- [bepuphysics2 Benchmarks](../src/benchmarks/real-world/bepuphysics2/README.md) - Information on benchmarks of bepuphysics2 library. +- [Microsoft.ML Benchmarks datasets](../src/benchmarks/real-world/Microsoft.ML.Benchmarks/Input/README.md) - Information on datasets used for benchmarking of the Microsoft.ML library. +- [Benchmarks run in PowerShell](../src/benchmarks/real-world/PowerShell.Benchmarks/README.md) - Information on performance tests for different pieces of the library run using PowerShell. + +### GC Benchmarks + +- [ASP.NET Benchmarks errors](../src/benchmarks/gc/GC.Infrastructure/docs/ASPNETBenchmarks.md) - Information on main types of errors while running ASP.NET Benchmarks using crank. +- [Testing GC.Infrastructure](../src/benchmarks/gc/GC.Infrastructure/README.md) - Information on testing GC.Infrastructure. +- [GC.Analysis.API](../src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md) - Information on conducting GC, CPU and Threading analysis using .NET Interactive notebooks. +- [GC.Infrastructure Notebooks](../src/benchmarks/gc/GC.Infrastructure/Notebooks/README.md) - Information on notebooks that either provide examples or functionality for specialized analysis +- [Benchmark Analysis](../src/benchmarks/gc/GC.Infrastructure/Notebooks/BenchmarkAnalysis.md) - Information on a notebook which contains code for producing charts (and soon, tables) for GC benchmarks. It can currently process data +from the ASP.NET benchmarks obtained using crank as well as ETL data. + +## Running Scenarios + +- [Scenarios workflow](scenarios-workflow.md) - An introduction of how to run scenario tests. +- [Basic scenarios](basic-scenarios.md) - Specific instruction of how to run various basic scenarios. +- [Blazor scenarios](blazor-scenarios) - Specific instruction of how to run _New Blazorwasm Template Size On Disk_ scenarios. +- [Cross-gen scenarios](crossgen-scenarios.md) - Specific instruction of how to run _crossgen_ scenarios. +- [SDK scenarios](sdk-scenarios.md) - Specific instruction of how to run _SDK Build Throughput Scenario_ scenarios. diff --git a/docs/blazor-scenarios.md b/docs/blazor-scenarios.md index 4754ce80ced..b6088a7b203 100644 --- a/docs/blazor-scenarios.md +++ b/docs/blazor-scenarios.md @@ -82,6 +82,7 @@ Same instruction of [Step 4 in Scenario Tests Guide](scenarios-workflow.md#step- ## Command Matrix For the purpose of quick reference, the commands can be summarized into the following matrix: + | Scenario | Asset Directory | Precommand | Testcommand | Postcommand | Supported Framework | Supported Platform | |-------------------------------------|-----------------|-------------------------------------------------------------|-------------------------------------------------------------------|-------------|---------------------|--------------------| | SOD - New Blazor Template - Publish | blazor | pre.py publish --msbuild "/p:_TrimmerDumpDependencies=true" | test.py sod --scenario-name "SOD - New Blazor Template - Publish" | post.py | net7.0; net8.0 | Windows;Linux | diff --git a/docs/crossgen-scenarios.md b/docs/crossgen-scenarios.md index 8b5862e9180..b4e8312067b 100644 --- a/docs/crossgen-scenarios.md +++ b/docs/crossgen-scenarios.md @@ -188,6 +188,7 @@ python3 post.py ## Command Matrix For the purpose of quick reference, the commands can be summarized into the following matrix: + | Scenario | Asset Directory | Precommand | Testcommand | Postcommand | Supported Framework | Supported Platform | |----------------------------------------|-----------------|--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|-------------|---------------------|-------------------------| | Crossgen Throughput | crossgen | N/A | test.py crossgen --core-root \ --single \ | post.py | N/A | Windows-x64;Windows-x86 | diff --git a/eng/common/template-guidance.md b/eng/common/template-guidance.md index 98bbc1ded0b..35620d87f86 100644 --- a/eng/common/template-guidance.md +++ b/eng/common/template-guidance.md @@ -1,6 +1,6 @@ # Overview -Arcade provides templates for public (`/templates`) and 1ES pipeline templates (`/templates-official`) scenarios. Pipelines which are required to be managed by 1ES pipeline templates should reference `/templates-offical`, all other pipelines may reference `/templates`. +Arcade provides templates for public (`/templates`) and 1ES pipeline templates (`/templates-official`) scenarios. Pipelines which are required to be managed by 1ES pipeline templates should reference `/templates-offical`, all other pipelines may reference `/templates`. ## How to use @@ -12,7 +12,7 @@ Basic guidance is: See [azure-pipelines.yml](../../azure-pipelines.yml) (templates-official example) or [azure-pipelines-pr.yml](../../azure-pipelines-pr.yml) (templates example) for examples. -#### The `templateIs1ESManaged` parameter +### The `templateIs1ESManaged` parameter The `templateIs1ESManaged` is available on most templates and affects which of the variants is used for nested templates. See [Development Notes](#development-notes) below for more information on the `templateIs1ESManaged1 parameter. @@ -23,6 +23,7 @@ The `templateIs1ESManaged` is available on most templates and affects which of t 1ES pipeline templates impose a policy where every publish artifact execution results in additional security scans being injected into your pipeline. When using `templates-official/jobs/jobs.yml`, Arcade reduces the number of additional security injections by gathering all publishing outputs into the [Build.ArtifactStagingDirectory](https://learn.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#build-variables-devops-services), and utilizing the [outputParentDirectory](https://eng.ms/docs/cloud-ai-platform/devdiv/one-engineering-system-1es/1es-docs/1es-pipeline-templates/features/outputs#multiple-outputs) feature of 1ES pipeline templates. When implementing your pipeline, if you ensure publish artifacts are located in the `$(Build.ArtifactStagingDirectory)`, and utilize the 1ES provided template context, then you can reduce the number of security scans for your pipeline. Example: + ``` yaml # azure-pipelines.yml extends: @@ -59,7 +60,7 @@ Note: Multiple outputs are ONLY applicable to 1ES PT publishing (only usable whe ## Development notes -**Folder / file structure** +### Folder / file structure ``` text eng\common\ diff --git a/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md b/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md index 8df7b0fc85b..d21abb84efd 100644 --- a/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md +++ b/src/benchmarks/gc/GC.Infrastructure/GC.Analysis.API/README.md @@ -7,7 +7,7 @@ This repository contains all the code responsible for conducting GC, CPU and Thr 1. Install all dependencies by: 1. [Installing VSCode](https://code.visualstudio.com/Download) - install vscode using the installer; downloading a zip file of the exe will result in issues with the ``Install.cmd`` script. 2. [Installing the .NET6 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/6.0) - 3. Ensure you have Jupyter: + 3. Ensure you have Jupyter (one of the following options): 1. Install python using the Windows Store. 2. Manually install Jupyter: 1. ``pip`` is in your PATH: