Add readmes to reflection #76567
Add readmes to reflection #76567
Conversation
steveharter
added
the
documentation
|
Tagging subscribers to this area: @dotnet/area-system-reflection Issue DetailsAdded readmes; these are fairly bare-bones for now. General layout is one "overview" doc that links all of the other readme.md files (one per folder\library) where each of those links back to the overview for the description of the "Status" column. The "status" entries are somewhat debatable for
|
There was a problem hiding this comment.
The System.Reflection.Extensions, Primitives and TypeExtensions NuGet packages should not be used by anything compatible with .NET Standard 2.0 (they will blow up the number of transitive dependencies). I would not mention them at all.
The System.Reflection.Emit* packages are needed only when targeting .NET Standard 2.0 (simplifying, actually a bit more complicated), since they became inbox in .NET Standard 2.1. Referencing them will increase dependencies (although not as badly as the other three packages). I would explain that only those targeting .NET Standard 2.0 need to target them.
|
@steveharter Are these readme files about adhering to a new policy or rather an effort to improve understanding for the community? I like the idea in principle but some of the content seems like it belongs in the official doc site rather than buried in the repo. |
In #63401, we decided on readme docs per library to advertise the investment status for each. With these, we can also give some technical overview info targeted at contributors (as well as team members). Some of the info does overlap with the official product docs, but the audience is intended to be different. This is our first one of them though, so we can refine here and as we progress. |
There was a problem hiding this comment.
I applied some feedback/ideas in a pull request that I sent to your fork, @steveharter. Since the ideas are opinionated, I didn't want to just push to your branch though.
There was a problem hiding this comment.
One last review from my side, @steveharter. This time I was reviewing the content more thoroughly. I suggested some more verbiage in some of the Status and Deployment sections, drawing from @teo-tsirpanis's comment.
They're just suggestions though; so I approve either way. Thanks again for getting the first round of these in and defining the structure/pattern!
| - **Legacy** | ||
| - Not under development; maintained for compatibility | ||
| - Issues are likely to be closed without fixes | ||
| - PRs are unlikely to be accepted |
There was a problem hiding this comment.
| - PRs are unlikely to be accepted | |
| - PRs are unlikely to be accepted |
We should clarify our stance on rock-polishing PRs (e.g. PRs enabling new analyzer and style-cop warnings) going into these libraries. There is a lot of churn from these PRs today. Is this churn still ok?
There was a problem hiding this comment.
Good question. So far, it's been case-by-case. 🤔
ghost
locked as resolved and limited conversation to collaborators
Added readmes; these are fairly bare-bones for now. This is part of a larger effort (see #63401) to help external contributors determine our current investment level for a library and whether it is (un)likely changes to that library will be made.
General layout is one README.md file per folder\library where each of those links back to a
libraries\README.mdfor the description of the "Status" column.The "status" entries are somewhat debatable for
LegacyvsInactiveespecially for the assemblies that are small and essentially forward to the runtime.