diff --git a/INDEX.md b/INDEX.md new file mode 100644 index 000000000..ef2d1a301 --- /dev/null +++ b/INDEX.md @@ -0,0 +1,84 @@ + + +# Meta + +| Design Name | +| ----------- | +| [Proposal Template](meta/template.md) | +| [Proposals](meta/proposals.md) | + +# Accepted + +| Year | Design Name | Owner | +| ---- | ----------- | ----- | +| 2018 | [.NET Core SDK Versioning](accepted/2018/sdk-version-scheme.md) | [Kathleen Dollard](https://github.com/KathleenDollard) | +| 2018 | [.NET Platform Dependent Intrinsics](accepted/2018/platform-intrinsics.md) | [Russell Hadley](https://github.com/russellhadley) | +| 2018 | [Automatic Binding Redirection By Default](accepted/2018/automatic-redirects-by-default/automatic-redirects-by-default.md) | [Immo Landwerth](https://github.com/terrajobst), [Rainer Sigwald](https://github.com/rainersigwald) | +| 2018 | [CLI Syntax Guidelines](accepted/2018/cli-syntax-guideline.md) | [Kathleen Dollard](https://github.com/KathleenDollard) | +| 2018 | [Cross-Platform Performance Monitoring Design](accepted/2018/cross-platform-performance-monitoring.md) | [Brian Robbins](https://github.com/brianrob) | +| 2018 | [Extensible File Enumeration](accepted/2018/file-enumeration.md) | [Immo Landwerth](https://github.com/terrajobst), [Jeremy Kuhne](https://github.com/jeremykuhne) | +| 2018 | [Package Information in API Reference](accepted/2018/package-doc/package-doc.md) | [Immo Landwerth](https://github.com/terrajobst), [Wes Haggard](https://github.com/weshaggard) | +| 2018 | [Performance Profiling Controller Design](accepted/2018/performance-profiling-controller.md) | [Brian Robbins](https://github.com/brianrob) | +| 2018 | [Rolling self-contained .NET Core app deployments forward to the latest patch](accepted/2018/self-contained-roll-forward.md) | [Daniel Plaisted](https://github.com/dsplaisted) | +| 2018 | [Standardized Environment Variables for CI Services](accepted/2018/build/standard-ci-env-variables.md) | [Tomáš Matoušek](https://github.com/tmat) | +| 2018 | [Windows Compatibility Pack](accepted/2018/compat-pack/compat-pack.md) | [Immo Landwerth](https://github.com/terrajobst), [Wes Haggard](https://github.com/weshaggard) | +| 2019 | [.NET Core GC Support for Docker Limits](accepted/2019/support-for-memory-limits.md) | [Rich Lander](https://github.com/richlander) | +| 2019 | [Background](accepted/2019/targeting-packs-and-runtime-packs.md) | [Rich Lander](https://github.com/richlander), [Nick Guerrera](https://github.com/nguerrera) | +| 2019 | [Runtime Binding Behavior](accepted/2019/runtime-binding.md) | [Rich Lander](https://github.com/richlander) | +| 2019 | [System.Index and System.Range](accepted/2019/system-range/system-range.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [.NET 5 Minimum OS Versioning](accepted/2020/minimum-os-version/minimum-os-version.md) | [Mikayla Hutchinson](https://github.com/mhutch) | +| 2020 | [.NET Core 3.0 AppDomain Replacement Design and Guidance](accepted/2020/AssemblyLoadContext/AppDomainReplacement.md) | [Steve MacLean](https://github.com/sdmaclea) | +| 2020 | [.NET Optional SDK Workloads](accepted/2020/workloads/workloads.md) | [Rich Lander](https://github.com/richlander) | +| 2020 | [.NET Runtime Form Factors](accepted/2020/form-factors.md) | [Rich Lander](https://github.com/richlander), [Jan Kotas](https://github.com/jkotas) | +| 2020 | [.NET SDK Workload Manifests](accepted/2020/workloads/workload-manifest.md) | [Rich Lander](https://github.com/richlander) | +| 2020 | [ASN.1 BER/CER/DER Reader & Writer](accepted/2020/asnreader/asnreader.md) | [Jeremy Barton](https://github.com/bartonjs) | +| 2020 | [Annotating APIs as unsupported on specific platforms](accepted/2020/platform-exclusion/platform-exclusion.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Annotating platform-specific APIs and detecting its use](accepted/2020/platform-checks/platform-checks.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Better Obsoletion](accepted/2020/better-obsoletion/better-obsoletion.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [BinaryFormatter Obsoletion Strategy](accepted/2020/better-obsoletion/binaryformatter-obsoletion.md) | [Levi Broderick](https://github.com/GrabYourPitchforks) | +| 2020 | [CBOR Reader & Writer](accepted/2020/cbor/cbor.md) | [Eirik Tsarpalis](https://github.com/eiriktsarpalis) | +| 2020 | [Easy Acquisition of .NET Framework Targeting Packs](accepted/2020/targeting-packs/targeting-packs.md) | [Immo Landwerth](https://github.com/terrajobst), [Daniel Plaisted](https://github.com/dsplaisted) | +| 2020 | [Feature switch](accepted/2020/feature-switch.md) | [Vitek Karas](https://github.com/vitek-karas) | +| 2020 | [Globalization Support in .NET 5](accepted/2020/mono-convergence/globalization-support-in-.net5.md) | [Steve Pfister](https://github.com/steveisok) | +| 2020 | [Improve Activity API usability and OpenTelemetry integration](accepted/2020/diagnostics/activity-improvements.md) | [Sourabh Shirhatti](https://github.com/shirhatti), [Ankit Srivastava](https://github.com/ankit-oss) [Tarek Mahmoud Sayed](https://github.com/tarekgh) | +| 2020 | [Improve Activity API usability and OpenTelemetry integration (Part 2)](accepted/2020/diagnostics/activity-improvements-2.md) | [Sourabh Shirhatti](https://github.com/shirhatti), [Tarek Mahmoud Sayed](https://github.com/tarekgh) | +| 2020 | [Install location search for .NET Core](accepted/2020/install-locations.md) | [Vitek Karas](https://github.com/vitek-karas) | +| 2020 | [JSON extension methods for HttpClient](accepted/2020/json-http-extensions/json-http-extensions.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Linking the .NET Libraries](accepted/2020/linking-libraries.md) | [Eric Erhardt](https://github.com/eerhardt) | +| 2020 | [MSBuild SDK Resolvers and optional workloads in .NET 5](accepted/2020/workloads/workload-resolvers.md) | [Rich Lander](https://github.com/richlander) | +| 2020 | [Marking APIs that are unsupported by Blazor WebAssembly](accepted/2020/blazor-unsupported-apis/blazor-unsupported-apis.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Marking Windows-only APIs](accepted/2020/windows-specific-apis/windows-specific-apis.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [OR_GREATER preprocessor symbols for TFMs](accepted/2020/or-greater-defines/or-greater-defines.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Obsoletions in .NET 5](accepted/2020/better-obsoletion/obsoletions-in-net5.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Overview and goals](accepted/2020/serializer/SerializerGoals5.0.md) | [Steve Harter](https://github.com/steveharter) | +| 2020 | [Platform Specific HttpClient Support in dotnet/runtime](accepted/2020/mono-convergence/platform-specific-httpclient.md) | [Steve Pfister](https://github.com/steveisok) | +| 2020 | [Portable PDB](accepted/2020/diagnostics/portable-pdb.md) | [Tomáš Matoušek](https://github.com/tmat) | +| 2020 | [Proposal for global.json](accepted/2020/global-json-updates.md) | [Kathleen Dollard](https://github.com/KathleenDollard) | +| 2020 | [Publishing and Consuming Symbols and Source for Debugging](accepted/2020/diagnostics/debugging-with-symbols-and-sources.md) | [Tomáš Matoušek](https://github.com/tmat) | +| 2020 | [Reproducible Build Validation](accepted/2020/reproducible-builds.md) | [Claire Novotny](https://github.com/clairernovotny), [Jared Parsons](https://github.com/jaredpar) | +| 2020 | [Single-file Publish](accepted/2020/single-file/design.md) | [Swaroop Sridhar](https://github.com/swaroop-sridhar) | +| 2020 | [Single-file Publish for .NET Core 3.0](accepted/2020/single-file/design_3_0.md) | [Swaroop Sridhar](https://github.com/swaroop-sridhar) | +| 2020 | [Source Link](accepted/2020/diagnostics/source-link.md) | [Tomáš Matoušek](https://github.com/tmat) | +| 2020 | [Target Framework Names in .NET 5](accepted/2020/net5/net5.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2020 | [Type for holding & converting binary data](accepted/2020/binary-data/binary-data.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2021 | [.NET 6.0 Target Frameworks](accepted/2021/net6.0-tfms/net6.0-tfms.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2021 | [Designs](accepted/2021/statics-in-interfaces/designs/README.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2021 | [Requirements](accepted/2021/statics-in-interfaces/requirements/README.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2021 | [Scenarios](accepted/2021/statics-in-interfaces/scenarios/README.md) | [Immo Landwerth](https://github.com/terrajobst) | +| 2021 | [Statics in Interfaces](accepted/2021/statics-in-interfaces/README.md) | [Immo Landwerth](https://github.com/terrajobst) | + +# Proposed + +| Design Name | Owner | +| ----------- | ----- | +| [Flexible HTTP APIs](proposed/flexible-http.md) | [Cory Nelson](https://github.com/scalablecory), [Geoff Kizer](https://github.com/geoffkizer) | +| [Readonly references in C# and IL verification.](proposed/verifiable-ref-readonly.md) | | +| [Ref returns in C# and IL verification.](proposed/verifiable-ref-returns.md) | | diff --git a/README.md b/README.md index cf4f07f8a..2f6f614a9 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # .NET Design Proposals -This repo contains [design proposals](meta/proposals.md) for the .NET platform. -It focuses on designs for the runtime, framework, and the SDK. For others, see: +This repo contains [design proposals](meta/proposals.md) for the .NET platform. For a complete listing, see [INDEX.md](INDEX.md). +This repo focuses on designs for the runtime, framework, and the SDK. For others, see: * [C# Language Designs and Suggestions (dotnet/csharplang)](https://github.com/dotnet/csharplang) * [VB Language Designs and Suggestions (dotnet/vblang)](https://github.com/dotnet/vblang) diff --git a/accepted/2018/build/standard-ci-env-variables.md b/accepted/2018/build/standard-ci-env-variables.md index 13129def1..16a470e78 100644 --- a/accepted/2018/build/standard-ci-env-variables.md +++ b/accepted/2018/build/standard-ci-env-variables.md @@ -1,5 +1,7 @@ # Standardized Environment Variables for CI Services +**Dev** [Tomáš Matoušek](https://github.com/tmat) + The .NET Core SDK is implementing new scenarios that require source control manager information. We want to make it very easy to embed repo-specific information in built assets as a means of creating a strong relationship between binary and source. To make it possible to provide application platform provided experiences across CI services, we need a standardized set of environment variables that are supported across those same CI services. Ideally, this set of environment variables would be supported across multiple CI services and useful for multiple application environments, not just .NET. diff --git a/accepted/2018/cli-syntax-guideline.md b/accepted/2018/cli-syntax-guideline.md index a604b5e2d..c723b135d 100644 --- a/accepted/2018/cli-syntax-guideline.md +++ b/accepted/2018/cli-syntax-guideline.md @@ -1,5 +1,7 @@ # CLI Syntax Guidelines +**PM** [Kathleen Dollard](https://github.com/KathleenDollard) + Many tools have a CLI (command-line interface) which allows users to type English words to describe commands. This post describes how we build the syntax for commands in the .NET Core CLI. This articulates the guidelines that are similar to behavior of other CLIs, including Git (git), Angular (ng) and Azure (az). These guidelines were adopted as a goal for the CLI during .NET Core SDK 2.1.300 development. This version implements these goals for new features. Future SDKs will bring CLI syntax in line with these guidelines, while allowing existing syntax for backwards compatibility. diff --git a/accepted/2018/cross-platform-performance-monitoring.md b/accepted/2018/cross-platform-performance-monitoring.md index aa9ff9db0..3a2006d2b 100644 --- a/accepted/2018/cross-platform-performance-monitoring.md +++ b/accepted/2018/cross-platform-performance-monitoring.md @@ -1,4 +1,6 @@ -# Cross-Platform Performance Monitoring Design # +# Cross-Platform Performance Monitoring Design + +**Dev** [Brian Robbins](https://github.com/brianrob) ### Introduction ### @@ -63,4 +65,4 @@ Consumption of tracing data, including aggregated counter data, will be done via - CONSIDER: Make EventSource pass a strongly typed object representing the payload fields. - Extra Credit: Move the LTTng implementation behind the EventPipe - Right now, calls to LTTng sit right next to the EventPipe. They should be moved behind the EventPipe just like ETW (above). - - This isn't specifically required for performance counters, but can/should be done especially if it cleans up the code or makes things easier. \ No newline at end of file + - This isn't specifically required for performance counters, but can/should be done especially if it cleans up the code or makes things easier. diff --git a/accepted/2018/file-enumeration.md b/accepted/2018/file-enumeration.md index 0c3b672b2..6851887df 100644 --- a/accepted/2018/file-enumeration.md +++ b/accepted/2018/file-enumeration.md @@ -1,6 +1,7 @@ # Extensible File Enumeration -**PM** [Immo Landwerth](https://github.com/terrajobst) | **Dev** [Jeremy Kuhne](https://github.com/jeremykuhne) +**PM** [Immo Landwerth](https://github.com/terrajobst) | +**Dev** [Jeremy Kuhne](https://github.com/jeremykuhne) Enumerating files in .NET provides limited configurability. You can specify a simple DOS style pattern and whether or not to look recursively. More complicated filtering requires post filtering all results which can introduce a significant performance drain. @@ -453,4 +454,4 @@ namespace System.IO } ``` -These routes would require adding some overhead to check for the "mock" data on every property call. Perf impact would need to be measured. \ No newline at end of file +These routes would require adding some overhead to check for the "mock" data on every property call. Perf impact would need to be measured. diff --git a/accepted/2018/performance-profiling-controller.md b/accepted/2018/performance-profiling-controller.md index 0c8705def..a4fe3c300 100644 --- a/accepted/2018/performance-profiling-controller.md +++ b/accepted/2018/performance-profiling-controller.md @@ -1,5 +1,7 @@ # Performance Profiling Controller Design # +**Dev** [Brian Robbins](https://github.com/brianrob) + ### Introduction ### This document describes the end-to-end scenarios and work required to build a performance profiling controller for .NET Core. The controller is responsible for control of the profiling infrastructure and exposure of performance data produced by .NET performance diagnostics components in a simple and cross-platform way. diff --git a/accepted/2018/platform-intrinsics.md b/accepted/2018/platform-intrinsics.md index 7197a2f4e..7c247051f 100644 --- a/accepted/2018/platform-intrinsics.md +++ b/accepted/2018/platform-intrinsics.md @@ -1,5 +1,7 @@ # .NET Platform Dependent Intrinsics +**Dev** [Russell Hadley](https://github.com/russellhadley) + ## Introduction The dotnet ecosystem supports many platforms and hardware architectures, and through its runtime implementation, ensuring that any MSIL has reasonable diff --git a/accepted/2018/sdk-version-scheme.md b/accepted/2018/sdk-version-scheme.md index 38b822e25..28e57cd92 100644 --- a/accepted/2018/sdk-version-scheme.md +++ b/accepted/2018/sdk-version-scheme.md @@ -1,5 +1,7 @@ # .NET Core SDK Versioning +**PM** [Kathleen Dollard](https://github.com/KathleenDollard) + .NET Core runtimes and SDKs are used together. They release independently, so it has been a challenge picking sensible version numbers. Going forward, the first and second positions of the version number will match for the Runtime and SDK. The third position will not match since the Runtime and SDK release independently. The Runtime will follow [semantic versioning](https://semver.org/). The first, second and third positions of the Runtime version number will correspond to major, minor and patch versions, respectively. @@ -87,4 +89,4 @@ Behavior when SDK versions using both schemes are present: | 2.1.1 | 2.1.3, 2.1.300 | 2.1.3 will run | | 2.1.1 | 2.1.300 | error | -> Note: We will ship the updated SDK selection behavior with both .NET Core Runtime 2.1 and .NET Core SDK 2.1.300. This update in behavior is only important if your global.json includes a version that is 2.1.0 or higher and that SDK version is not present. From the release of .NET Core SDK 2.1.100 until the release of .NET Core SDK 2.1.300, we recommend you ensure that any versions of the SDK referenced by global.json is present on the machine. This approach avoids selecting a higher feature version of the SDK than you probably expect given the version specified in global.json \ No newline at end of file +> Note: We will ship the updated SDK selection behavior with both .NET Core Runtime 2.1 and .NET Core SDK 2.1.300. This update in behavior is only important if your global.json includes a version that is 2.1.0 or higher and that SDK version is not present. From the release of .NET Core SDK 2.1.100 until the release of .NET Core SDK 2.1.300, we recommend you ensure that any versions of the SDK referenced by global.json is present on the machine. This approach avoids selecting a higher feature version of the SDK than you probably expect given the version specified in global.json diff --git a/accepted/2018/self-contained-roll-forward.md b/accepted/2018/self-contained-roll-forward.md index b97a43ab4..a500ff76f 100644 --- a/accepted/2018/self-contained-roll-forward.md +++ b/accepted/2018/self-contained-roll-forward.md @@ -1,5 +1,7 @@ # Rolling self-contained .NET Core app deployments forward to the latest patch +**Dev** [Daniel Plaisted](https://github.com/dsplaisted) + ## Goal Self-contained deployments of .NET Core apps should roll forward to the latest patch version of the .NET Core runtime. Framework-dependent deployments should by default target the ".0" patch version of the .NET Core runtime, and will be rolled forward to the latest patch version available on the machine when they are run. @@ -80,4 +82,4 @@ The difference is that the reference to `Microsoft.NETCore.App` is implicit, whi ## Notes -- `publish --no-build` - For this to work, you will need to have built with the RID specified (ie `dotnet build -r {rid}`) \ No newline at end of file +- `publish --no-build` - For this to work, you will need to have built with the RID specified (ie `dotnet build -r {rid}`) diff --git a/accepted/2019/runtime-binding.md b/accepted/2019/runtime-binding.md index 8e7f8da1e..936f57a69 100644 --- a/accepted/2019/runtime-binding.md +++ b/accepted/2019/runtime-binding.md @@ -1,5 +1,7 @@ # Runtime Binding Behavior +**PM** [Rich Lander](https://github.com/richlander) + [Framework-dependent](https://docs.microsoft.com/dotnet/core/deploying/#framework-dependent-deployments-fdd) applications require a .NET Core host to find a compatible runtime from a central location. The behavior of runtime binding is critical for both application compatibility and runtime deployment convenience. [Self-contained](https://docs.microsoft.com/dotnet/core/deploying/#self-contained-deployments-scd) apps don't have this need, because there is only one runtime they will ever use. This document proposes a model that works for both apps and managed COM components/hosting. diff --git a/accepted/2019/support-for-memory-limits.md b/accepted/2019/support-for-memory-limits.md index 88934f588..28d28799b 100644 --- a/accepted/2019/support-for-memory-limits.md +++ b/accepted/2019/support-for-memory-limits.md @@ -1,5 +1,7 @@ # .NET Core GC Support for Docker Limits +**PM** [Rich Lander](https://github.com/richlander) + .NET Core has support for [control groups](https://en.wikipedia.org/wiki/Cgroups) (cgroups), which is the basis of [Docker limits](https://docs.docker.com/config/containers/resource_constraints/). We found that the algorithm we use to honor cgroups works well for larger memory size limits (for example, >500MB), but that it is not possible to configure a .NET Core application to run indefinitely at lower memory levels. This document proposes an approach to support low memory size limits, <100MB. Note: Windows has a concept similar to cgroups called [job objects](https://docs.microsoft.com/windows/desktop/ProcThread/job-objects). .NET Core should honor job objects in the same way as cgroups, as appropriate. This document will focus on cgroups throughout. diff --git a/accepted/2019/targeting-packs-and-runtime-packs.md b/accepted/2019/targeting-packs-and-runtime-packs.md index be397f1a4..53d72ac73 100644 --- a/accepted/2019/targeting-packs-and-runtime-packs.md +++ b/accepted/2019/targeting-packs-and-runtime-packs.md @@ -1,5 +1,8 @@ # Background +**PM** [Rich Lander](https://github.com/richlander) | +**Dev** [Nick Guerrera](https://github.com/nguerrera) | + The objectives here are: 1. Summarize the new approach of FrameworkReferences, targeting packs and runtime packs diff --git a/accepted/2020/AssemblyLoadContext/AppDomainReplacement.md b/accepted/2020/AssemblyLoadContext/AppDomainReplacement.md index 37b93ec54..564df3658 100644 --- a/accepted/2020/AssemblyLoadContext/AppDomainReplacement.md +++ b/accepted/2020/AssemblyLoadContext/AppDomainReplacement.md @@ -1,5 +1,7 @@ # .NET Core 3.0 AppDomain Replacement Design and Guidance +**Dev** [Steve MacLean](https://github.com/sdmaclea) + .NET Core chose to not fully support the `System.AppDomain` type as implemented in .NET Framework diff --git a/accepted/2020/asnreader/asnreader.md b/accepted/2020/asnreader/asnreader.md index bf07185f2..a73d97acf 100644 --- a/accepted/2020/asnreader/asnreader.md +++ b/accepted/2020/asnreader/asnreader.md @@ -1,5 +1,6 @@ # ASN.1 BER/CER/DER Reader & Writer -[Jeremy Barton](https://github.com/bartonjs) + +**Dev** [Jeremy Barton](https://github.com/bartonjs) ASN.1 (Abstract Syntax Notation One), defined by [ITU-T X.680](https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-X.680-201508-I!!PDF-E&type=items), is a data modelling language used to describe objects used in cryptographic key transmission, X.509 public key certificates, diff --git a/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md b/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md index 8257450ed..321ce05dc 100644 --- a/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md +++ b/accepted/2020/better-obsoletion/binaryformatter-obsoletion.md @@ -1,5 +1,7 @@ # BinaryFormatter Obsoletion Strategy +**Dev** [Levi Broderick](https://github.com/GrabYourPitchforks) + This document applies to the following framework versions: * .NET 5.0+ diff --git a/accepted/2020/blazor-unsupported-apis/blazor-unsupported-apis.md b/accepted/2020/blazor-unsupported-apis/blazor-unsupported-apis.md index 88ded1a6d..bc27b2e78 100644 --- a/accepted/2020/blazor-unsupported-apis/blazor-unsupported-apis.md +++ b/accepted/2020/blazor-unsupported-apis/blazor-unsupported-apis.md @@ -1,5 +1,7 @@ # Marking APIs that are unsupported by Blazor WebAssembly +**PM** [Immo Landwerth](https://github.com/terrajobst) + As discussed in [dotnet/designs#143] we're adding an analyzer to detect usage of unsupported APIs. This analyzer requires a custom attribute applied to method, containing type, or assembly. @@ -237,4 +239,4 @@ Once the Windows attribution is done, I'll update this PR again. - UnsafeRegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, object, int, bool) - UnsafeRegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, object, long, bool) - UnsafeRegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, object, TimeSpan, bool) - - UnsafeRegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, object, uint, bool) \ No newline at end of file + - UnsafeRegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, object, uint, bool) diff --git a/accepted/2020/cbor/cbor.md b/accepted/2020/cbor/cbor.md index 2c44dee99..8c8c0044c 100644 --- a/accepted/2020/cbor/cbor.md +++ b/accepted/2020/cbor/cbor.md @@ -1,5 +1,6 @@ # CBOR Reader & Writer -[Eirik Tsarpalis](https://github.com/eiriktsarpalis) + +**Dev** [Eirik Tsarpalis](https://github.com/eiriktsarpalis) CBOR (Concise Binary Object Representation), as defined by [RFC 7049](https://tools.ietf.org/html/rfc7049), is a binary data format loosely based on JSON, emphasizing small message sizes, diff --git a/accepted/2020/diagnostics/activity-improvements-2.md b/accepted/2020/diagnostics/activity-improvements-2.md index 0f232530d..569d83b9b 100644 --- a/accepted/2020/diagnostics/activity-improvements-2.md +++ b/accepted/2020/diagnostics/activity-improvements-2.md @@ -1,5 +1,8 @@ # Improve Activity API usability and OpenTelemetry integration (Part 2) +**PM** [Sourabh Shirhatti](https://github.com/shirhatti) | +**Dev** [Tarek Mahmoud Sayed](https://github.com/tarekgh) + We have exposed [Activity APIs to improve the API usability and to integrate with OpenTelemetry](https://github.com/dotnet/designs/pull/98) (OT) to have `Activity` be suitable replacement for the OT Span type described by the [OT Specs](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span). We have received feedback regarding some OT blocked scenarios which need to be addressed in the Activity APIs and unblock the OT SDK implementation. [Design Review Notes and Video](https://github.com/dotnet/runtime/issues/38419#issuecomment-655054487) diff --git a/accepted/2020/diagnostics/activity-improvements.md b/accepted/2020/diagnostics/activity-improvements.md index 05976fc8a..53446c527 100644 --- a/accepted/2020/diagnostics/activity-improvements.md +++ b/accepted/2020/diagnostics/activity-improvements.md @@ -1,4 +1,4 @@ - # Improve Activity API usability and OpenTelemetry integration +# Improve Activity API usability and OpenTelemetry integration [Github issue](https://github.com/dotnet/runtime/issues/31373) has past discussion. diff --git a/accepted/2020/diagnostics/debugging-with-symbols-and-sources.md b/accepted/2020/diagnostics/debugging-with-symbols-and-sources.md index d0821220e..1f971c422 100644 --- a/accepted/2020/diagnostics/debugging-with-symbols-and-sources.md +++ b/accepted/2020/diagnostics/debugging-with-symbols-and-sources.md @@ -1,5 +1,7 @@ # Publishing and Consuming Symbols and Source for Debugging +**Dev** [Tomáš Matoušek](https://github.com/tmat) + Debugging with symbols and source makes developers much more efficient and effective at developing and debugging (including debugging crash dumps). Our goal is to make debugging with source and symbols a characteristic of the .NET ecosystem. This document outlines an end-to-end flow from library through to app development that enables symbols and source to always be available. The primary audience of this document are developers who participate in the .NET ecosystem, either as a producer or consumer of NuGet packages. diff --git a/accepted/2020/diagnostics/portable-pdb.md b/accepted/2020/diagnostics/portable-pdb.md index 3ca065f86..7949e2323 100644 --- a/accepted/2020/diagnostics/portable-pdb.md +++ b/accepted/2020/diagnostics/portable-pdb.md @@ -1,5 +1,7 @@ # Portable PDB # +**Dev** [Tomáš Matoušek](https://github.com/tmat) + .NET Core introduces a new symbol file (PDB) format - portable PDBs. Unlike traditional PDBs which are Windows-only, portable PDBs can be created and read on all platforms. ## What is a PDB? ## diff --git a/accepted/2020/diagnostics/source-link.md b/accepted/2020/diagnostics/source-link.md index 12f48d055..e86322e41 100644 --- a/accepted/2020/diagnostics/source-link.md +++ b/accepted/2020/diagnostics/source-link.md @@ -1,4 +1,7 @@ # Source Link + +**Dev** [Tomáš Matoušek](https://github.com/tmat) + Source Link is a developer productivity feature that allows unique information about an assembly's original source code to be embedded in its PDB during compilation. The [Roslyn](https://github.com/dotnet/roslyn/wiki/Roslyn%20Overview) compiler flag for Source Link is `/sourcelink:`. ## Why Source Link? diff --git a/accepted/2020/feature-switch.md b/accepted/2020/feature-switch.md index dc97780b7..ba294f193 100644 --- a/accepted/2020/feature-switch.md +++ b/accepted/2020/feature-switch.md @@ -1,4 +1,7 @@ # Feature switch + +**Dev** [Vitek Karas](https://github.com/vitek-karas) + The functionality available in the .NET libraries is getting bigger and wider with every release. Applications typically don't need or want all of it, which means when an app includes the libraries as part of it, app size is unnecessarily increased. With technologies like the linker, we have the ability to remove parts of the framework which the app doesn't use. These technologies have limitations based on existing public API patterns and code behavior, sometimes they can't determine what the app really needs. This proposal adds a way to explicitly disable functionality in the framework. ## Goals diff --git a/accepted/2020/form-factors.md b/accepted/2020/form-factors.md index b82c39ab2..ff57e098d 100644 --- a/accepted/2020/form-factors.md +++ b/accepted/2020/form-factors.md @@ -1,6 +1,7 @@ # .NET Runtime Form Factors -[Jan Kotas](https://github.com/jkotas) | [Rich Lander](https://github.com/richlander) +**PM** [Rich Lander](https://github.com/richlander) | +**Dev** [Jan Kotas](https://github.com/jkotas) Starting in about 2014, we started a journey to open source and consolidate the .NET platform into a single code base, experience and brand. Those initial goals are now almost complete, with .NET 5.0. It is now time to re-evaluate where the industry and .NET users are heading next, and to make choices for .NET that are aligned. The .NET runtime form-factors are a frequent topic of feedback and discussions -- with current and potential users -- in terms of how we should improve and change fundamental .NET execution characteristics and expand the scenarios in which .NET can be used. diff --git a/accepted/2020/global-json-updates.md b/accepted/2020/global-json-updates.md index 1cc0cbfc3..088a8945f 100644 --- a/accepted/2020/global-json-updates.md +++ b/accepted/2020/global-json-updates.md @@ -1,5 +1,7 @@ # Proposal for global.json +**PM** [Kathleen Dollard](https://github.com/KathleenDollard) + --- **NOTE:** diff --git a/accepted/2020/install-locations.md b/accepted/2020/install-locations.md index 4effd38b5..b33d47641 100644 --- a/accepted/2020/install-locations.md +++ b/accepted/2020/install-locations.md @@ -1,5 +1,7 @@ # Install location search for .NET Core +**Dev** [Vitek Karas](https://github.com/vitek-karas) + .NET Core has several cases where it needs to search for the install location of the runtime and SDKs. This document described the proposed algorithm for how this search will be done on all the supported platforms. ## .NET Core install layout diff --git a/accepted/2020/json-http-extensions/json-http-extensions.md b/accepted/2020/json-http-extensions/json-http-extensions.md index e58f92f35..3b4a44784 100644 --- a/accepted/2020/json-http-extensions/json-http-extensions.md +++ b/accepted/2020/json-http-extensions/json-http-extensions.md @@ -1,6 +1,6 @@ # JSON extension methods for HttpClient -**[Immo Landwerth](https://github.com/terrajobst)** +**PM** [Immo Landwerth](https://github.com/terrajobst) Serializing and deserializing JSON payloads from the network is a very common operation for clients, especially in the upcoming Blazor environment. Right now, diff --git a/accepted/2020/linking-libraries.md b/accepted/2020/linking-libraries.md index 2900b68d9..b7d7d2bfe 100644 --- a/accepted/2020/linking-libraries.md +++ b/accepted/2020/linking-libraries.md @@ -1,5 +1,7 @@ # Linking the .NET Libraries +**Dev** [Eric Erhardt](https://github.com/eerhardt) + When publishing a self-contained application, a .NET runtime is bundled together with the application. This bundling adds a significant amount of content to the packaged application. Depending on the complexity of the application, only a diff --git a/accepted/2020/minimum-os-version/minimum-os-version.md b/accepted/2020/minimum-os-version/minimum-os-version.md index d66e9c962..bef6bd94f 100644 --- a/accepted/2020/minimum-os-version/minimum-os-version.md +++ b/accepted/2020/minimum-os-version/minimum-os-version.md @@ -1,5 +1,7 @@ # .NET 5 Minimum OS Versioning +**Dev** [Mikayla Hutchinson](https://github.com/mhutch) + # Introduction It is common for apps and libraries to support running on older versions of the OS than the version against which they were compiled. This pattern involves using runtime checks to guard against calling APIs that are not available, and is encouraged and widely used on the Xamarin platforms (iOS, Android, Mac etc). diff --git a/accepted/2020/mono-convergence/globalization-support-in-.net5.md b/accepted/2020/mono-convergence/globalization-support-in-.net5.md index 47393daa1..1b249bc3a 100644 --- a/accepted/2020/mono-convergence/globalization-support-in-.net5.md +++ b/accepted/2020/mono-convergence/globalization-support-in-.net5.md @@ -1,5 +1,7 @@ # Globalization Support in .NET 5 +**Dev** [Steve Pfister](https://github.com/steveisok) + ## Overview Globalization in the .NET Core space has been handled by taking a dependency on the [icu4c](http://site.icu-project.org/home) library and p-invoking into it from managed code. This model has been successful for desktop and server modes mostly because they can afford to take on the disk space ICU requires. However, in the size restricted workloads, this is quite a different story as there are differences in platform support and tolerance of taking on a significantly sized dependency. diff --git a/accepted/2020/mono-convergence/platform-specific-httpclient.md b/accepted/2020/mono-convergence/platform-specific-httpclient.md index 26d2301f1..680e73df3 100644 --- a/accepted/2020/mono-convergence/platform-specific-httpclient.md +++ b/accepted/2020/mono-convergence/platform-specific-httpclient.md @@ -1,5 +1,7 @@ # Platform Specific HttpClient Support in dotnet/runtime +**Dev** [Steve Pfister](https://github.com/steveisok) + ## Overview The underlying networking libraries and capabilities in iOS, Android, and Wasm have required us to implement custom **HttpMessageHandler** classes using platform-specific APIs. Because each platform has unique API, different release pressures, and deeper infrastructure dependencies, the Mono team pushed the platform implementation into the individual SDKs. diff --git a/accepted/2020/serializer/SerializerGoals5.0.md b/accepted/2020/serializer/SerializerGoals5.0.md index 3558d5967..a86fdd26a 100644 --- a/accepted/2020/serializer/SerializerGoals5.0.md +++ b/accepted/2020/serializer/SerializerGoals5.0.md @@ -1,5 +1,7 @@ # Overview and goals +**Dev** [Steve Harter](https://github.com/steveharter) + April 28th, 2020. This document provides options and recommendations for 5.0 to handle overlapping serializer goals including reach, faster cold startup performance, reducing memory usage, and smaller size-on-disk. diff --git a/accepted/2020/single-file/design.md b/accepted/2020/single-file/design.md index eaa2703aa..f0028e3fa 100644 --- a/accepted/2020/single-file/design.md +++ b/accepted/2020/single-file/design.md @@ -1,5 +1,7 @@ # Single-file Publish +**Dev** [Swaroop Sridhar](https://github.com/swaroop-sridhar) + This document describes the design single-file apps in .NET 5.0. The design of single-file apps in .NET Core 3.0 can be found [here](design_3_0.md) diff --git a/accepted/2020/single-file/design_3_0.md b/accepted/2020/single-file/design_3_0.md index 4e8587b25..8a3ba9ab7 100644 --- a/accepted/2020/single-file/design_3_0.md +++ b/accepted/2020/single-file/design_3_0.md @@ -1,4 +1,6 @@ -# Single-file Publish +# Single-file Publish for .NET Core 3.0 + +**Dev** [Swaroop Sridhar](https://github.com/swaroop-sridhar) The design of single-file apps in .NET Core 3.0. diff --git a/accepted/2020/windows-specific-apis/windows-specific-apis.md b/accepted/2020/windows-specific-apis/windows-specific-apis.md index 8f70834c7..0b1094735 100644 --- a/accepted/2020/windows-specific-apis/windows-specific-apis.md +++ b/accepted/2020/windows-specific-apis/windows-specific-apis.md @@ -1,5 +1,7 @@ # Marking Windows-only APIs +**PM** [Immo Landwerth](https://github.com/terrajobst) + As discussed in [dotnet/runtime#33331] we're adding an analyzer to detect usage of platform-specific APIs. This analyzer requires a custom attribute applied to method, containing type, or assembly. diff --git a/accepted/2020/workloads/workload-manifest.md b/accepted/2020/workloads/workload-manifest.md index 1dfba6b3e..65a8ed1bb 100644 --- a/accepted/2020/workloads/workload-manifest.md +++ b/accepted/2020/workloads/workload-manifest.md @@ -1,5 +1,12 @@ # .NET SDK Workload Manifests +**PM** [Rich Lander](https://github.com/richlander) + +// FIXME: do these count as PMs/Devs? +Co-authored-by: Kathleen Dollard +Co-authored-by: Steve Kirbach +Co-authored-by: Stephen Toub + # Overview .NET SDK workload manifests describe workloads that are available to be installed in the .NET SDK. They provide version mappings that allow MSBuild targets and other SDK tools to resolve the packs that comprise these workloads from the SDK installation directory, and can be used to acquire, repair, and update the workloads and their components. diff --git a/accepted/2020/workloads/workload-resolvers.md b/accepted/2020/workloads/workload-resolvers.md index f576295c9..1816c91db 100644 --- a/accepted/2020/workloads/workload-resolvers.md +++ b/accepted/2020/workloads/workload-resolvers.md @@ -1,5 +1,12 @@ # MSBuild SDK Resolvers and optional workloads in .NET 5 +**PM** [Rich Lander](https://github.com/richlander) + +// FIXME: do these count as PMs/Devs? +Co-authored-by: Kathleen Dollard +Co-authored-by: Steve Kirbach +Co-authored-by: Stephen Toub + In .NET 5, we will add support for iOS and Android. The .NET SDK (formerly known as the .NET Core SDK) will be able to build projects targeting iOS and Android. However, the .NET SDK will not be a monolithic SDK with support for all possible project types. Rather, the iOS and Android support (and eventually more pieces) will be delivered as optional SDK workloads which may or may not be installed. This proposal covers how we will use MSBuild SDK resolvers to hook up the build logic from workloads at build time, and to handle scenarios where a workload required to build a project is not installed. ## Links diff --git a/accepted/2020/workloads/workloads.md b/accepted/2020/workloads/workloads.md index 1414858dd..eeff0167a 100644 --- a/accepted/2020/workloads/workloads.md +++ b/accepted/2020/workloads/workloads.md @@ -1,4 +1,11 @@ -# .NET Optional SDK Workloads +# .NET Optional SDK Workloads + +**PM** [Rich Lander](https://github.com/richlander) + +// FIXME: do these count as PMs/Devs? +Co-authored-by: Kathleen Dollard +Co-authored-by: Steve Kirbach +Co-authored-by: Stephen Toub In .NET 5.0, we will add support for iOS, Android, and Web assembly projects. Up until .NET 5.0, we’ve delivered all supported workloads via a monolithic SDK. As the supported workloads of the .NET SDK grow (and we want them to), it is no longer tenable to deliver an "all-in-one / one-size-fits-all" SDK distribution. There are many challenges to a large monolithic SDK, with product build time and distribution size being the most significant. Instead, all new workloads will be built and delivered separately from the SDK, and will be acquirable via your favorite installation tool (like the Visual Studio Installer, a Linux package manager, or the .NET CLI). In the fullness of time, we intend for all .NET workloads to follow this pattern, resulting in a very small and focused SDK. diff --git a/meta/proposals.md b/meta/proposals.md index 6b19f3ed5..363d88d68 100644 --- a/meta/proposals.md +++ b/meta/proposals.md @@ -95,4 +95,4 @@ All of this is much easier if there is a written form of a proposal: In short, writing proposals can help us in being more efficient and more effective with the resources we have. It might be counter intuitive, but it's a -tool that helps us to be more agile. \ No newline at end of file +tool that helps us to be more agile. diff --git a/proposed/flexible-http.md b/proposed/flexible-http.md index eaf59f605..6d6fb03c8 100644 --- a/proposed/flexible-http.md +++ b/proposed/flexible-http.md @@ -1,6 +1,7 @@ # Flexible HTTP APIs -[Cory Nelson](https://github.com/scalablecory), [Geoff Kizer](https://github.com/geoffkizer) +**Dev** [Cory Nelson](https://github.com/scalablecory) | +**Dev** [Geoff Kizer](https://github.com/geoffkizer) This design doc describes a set of flexible, high-performance APIs for HTTP. diff --git a/proposed/verifiable-ref-readonly.md b/proposed/verifiable-ref-readonly.md index 4dabb4ccb..96c1ae771 100644 --- a/proposed/verifiable-ref-readonly.md +++ b/proposed/verifiable-ref-readonly.md @@ -1,4 +1,4 @@ -# Readonly references in C# and IL verification. # +# Readonly references in C# and IL verification. # The goal of this document is to specify additional IL verification rules that would allow C# code that utilizes readonly references to be formally verifiable. @@ -114,4 +114,4 @@ Signatures that differ in terms of `readonly` are not compatible. NOTE: The modifiers on parameters and returns are ignored here. That is existing behavior and it is not changed to allow delegate creation regardless of whether target method is virtual and uses modifiers or not. NOTE: The requirement could be relaxed to allow readonly references be compatible with ordinary references in return position and reverse in parameter positions, if more complex rules can be justified. - \ No newline at end of file + diff --git a/update-index b/update-index new file mode 100755 index 000000000..9007e8c6e --- /dev/null +++ b/update-index @@ -0,0 +1,149 @@ +#!/usr/bin/python3 + +import logging +import os +import re +import sys +from typing import List, NamedTuple, Optional + +def main() -> int: + logging.basicConfig(format='%(levelname)s: %(message)s', level=logging.WARNING) + log = logging.getLogger(__name__) + + print('''''') + print() + + print('# Meta') + print() + designs = [] + for dirname, subdirs, files in os.walk('meta'): + for f in files: + path = os.path.join(dirname, f) + if path.endswith('.md'): + design = parse_design(path, True, log) + if design: + designs.append(design) + + designs = sorted(designs, key=lambda d: d.title) + print('| Design Name |') + print('| ----------- |') + for design in designs: + print('| [%s](%s) |' % (design.title, design.path)) + print() + + print('# Accepted') + print() + designs = [] + for dirname, subdirs, files in os.walk('accepted'): + for f in files: + path = os.path.join(dirname, f) + if path.endswith('.md'): + design = parse_design(path, False, log) + if design: + designs.append(design) + + designs = sorted(designs, key=lambda d: d.title) + designs = sorted(designs, key=lambda d: d.year) + print('| Year | Design Name | Owner |') + print('| ---- | ----------- | ----- |') + for design in designs: + owners = [] + owners.extend(design.pm) + owners.extend(design.dev) + print('| %s | [%s](%s) | %s |' % (design.year, + design.title, + design.path, + ', '.join(owners))) + print() + + print('# Proposed') + print() + designs = [] + for dirname, subdirs, files in os.walk('proposed'): + for f in files: + path = os.path.join(dirname, f) + if path.endswith('.md'): + design = parse_design(path, True, log) + if design: + designs.append(design) + + designs = sorted(designs, key=lambda d: d.title) + print('| Design Name | Owner |') + print('| ----------- | ----- |') + for design in designs: + owners = [] + owners.extend(design.pm) + owners.extend(design.dev) + print('| [%s](%s) | %s |' % (design.title, design.path, ', '.join(owners))) + print() + + return 0 + +class Design(NamedTuple): + path: str + title: str + year: Optional[int] + pm: List[str] + dev: List[str] + +def parse_design(f, everything_is_a_design: bool, log) -> Optional[Design]: + PM_DEV_REGEX = r'^\*\*(?:Libraries)? *(PM|Dev) ?\*\*(.+)$' + + title = '' + year = None + try: + year = int(f.split('/')[1]) + except ValueError: + pass + + dev: List[str] = [] + pm: List[str] = [] + + log.info(f'parsing {f}') + + with open(f) as proposal: + for line in proposal.readlines()[:10]: + line = line.strip() + if not title and line.startswith('#') and not line.startswith('##'): + title = line[1:] + if title.endswith(' #'): + title = title[:-2] + title = title.strip() + pm_or_dev_match = re.search(PM_DEV_REGEX, line) + if pm_or_dev_match: + role = pm_or_dev_match.group(1) + names = pm_or_dev_match.group(2) + # pipe char breaks how we use the name, plus it's not actually part of the name + names = names.replace('|', '') + if 'PM' in role: + a_pm = names.strip() + pm.append(a_pm) + if 'Dev' in role: + a_dev = names.strip() + a_dev = a_dev.replace('|', '') + dev.append(a_dev) + + # Some designs have sub-designs, so use a heuristic relying on + # PM/Dev fields to find the 'main' designs + if not everything_is_a_design and not pm and not dev: + log.debug(f'{f} is NOT a design') + return None + + if not title: + log.warning(f'Unable to parse a title from design {f}') + + if not pm and not dev: + log.warning(f'No Dev or PM for {f}') + + return Design(f, title, year, pm, dev) + +if __name__ == '__main__': + sys.exit(main())