search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.26k stars 5.89k forks source link

Update feature switches documentation #41739

Open LakshanF opened 3 months ago

LakshanF commented 3 months ago

Ensure that the feature switches documentation is up to date with the recently added new ones. Also, it would be good to have the AppContext settings for each build property.

The following public feature switches are not yet in the docs

These public feature switches are documented but the AppContextsetting strings are not defined.

MichalStrehovsky commented 3 months ago

Cc @eerhardt @dotnet/illink I don't know how may of these are actually implementation details. The repo docs in the dotnet/runtime repo are not public docs, they're docs on implementation details. E.g. I'm not sure about scenarios where we'd want to support/document the appcontext switches.

eerhardt commented 3 months ago

I think there's a different level of "public" between things like the runtime and higher-level app models (like MAUI and WinForms), versus "public" that we want .NET application developers to be aware of.

A decent amount of these feature switches should never be used by .NET application developers, but they were created for specific app model needs. For example DisableDependencyInjectionDynamicEngine was created for Android, but could be useful for other app models in the future. These kinds of switches feel like they shouldn't be given the same level of publicity as things like InvariantGlobalization, which can be specified by application devs.

I think the switches that are meant for .NET application developers should be documented on learn.microsoft.com. The switches that aren't, I don't think they need to be.

Of the above list, ones that I think application developers should be aware of:

ilonatommy commented 3 months ago

@eerhardt, you are correct, we want to make sure developers are aware of HybridGlobalization on WASM. We have it in our docs but adding it here as well would be helpful.

sbomer commented 1 month ago

I'll make a suggestion: going forward, any new feature switches intended for higher-level app models but not for app developers should be prefixed with an underscore.

I think we'll inevitably encounter advanced app developers who want the same level of control as the higher-level app models by using the same feature switches - and they will start using the switches whether or not they are documented on MS learn. The best way to signal caution to these app developers is by the underscore naming convention.

sbomer commented 1 month ago

I would also like the feature switches that are only useful as escape hatches for warning-disabled trimming to be undocumented on ms learn, and use the non-public naming convention. See related discussion at https://github.com/dotnet/runtime/pull/107713#discussion_r1756873047.