Add package readmes - #91210

Merged
ViktorHofer merged 62 commits into
mainfrom
InSourcePackageReadme
Sep 18, 2023
Merged

Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom
InSourcePackageReadme

Conversation

@ViktorHofer

@ViktorHoferViktorHofer commented Aug 28, 2023•
edited
Loading

Copy link
Copy Markdown
Member

Contributes to #59630

One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.

Ask

To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.

Why

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.

How

This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.

I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.

Priority 1 (.NET 8 RC 2)

Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.

The below list is sorted by download count.

PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅

Priority 2 (.NET 8 / .NET 9)

This list is sorted alphabetically.

PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit

✅ (:white_check_mark:) -> reviewed & approved

🕜 (:clock130:) -> under review

cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight

@ViktorHoferViktorHofer added this to the 8.0.0 milestone Aug 28, 2023
@ghost

ghost commented Aug 28, 2023

Copy link
Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta
See info in area-owners.md if you want to be subscribed.

Issue Details

Contributes to #59630

One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.

Ask

To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.

Why

The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.

How

This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.

For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md

I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.

Priority 1 (.NET 8 RC 2)

Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.

  • Microsoft.Bcl.AsyncInterfaces
  • System.CodeDom
  • System.Data.Odbc
  • System.Data.OleDb
  • System.Diagnostics.EventLog
  • System.DirectoryServices
  • System.DirectoryServices.AccountManagement
  • System.IO.Ports
  • System.Management
  • System.Net.Http.Json
  • System.Runtime.Caching
  • System.Security.Permissions
  • System.ServiceProcess.ServiceController
  • System.Speech
  • System.Text.Encodings.Web
  • System.Windows.Extensions

Prio 2 (.NET 8 / .NET 9)

  • Microsoft.Bcl.Cryptography
  • Microsoft.Bcl.Numerics
  • Microsoft.Bcl.TimeProvider
  • Microsoft.Extensions.Caching.Abstractions
  • Microsoft.Extensions.Caching.Memory
  • Microsoft.Extensions.Configuration
  • Microsoft.Extensions.Configuration.Abstractions
  • Microsoft.Extensions.Configuration.Binder
  • Microsoft.Extensions.Configuration.CommandLine
  • Microsoft.Extensions.Configuration.EnvironmentVariables
  • Microsoft.Extensions.Configuration.FileExtensions
  • Microsoft.Extensions.Configuration.Ini
  • Microsoft.Extensions.Configuration.Json
  • Microsoft.Extensions.Configuration.UserSecrets
  • Microsoft.Extensions.Configuration.Xml
  • Microsoft.Extensions.DependencyInjection
  • Microsoft.Extensions.DependencyInjection.Abstractions
  • Microsoft.Extensions.DependencyInjection.Specification.Tests
  • Microsoft.Extensions.DependencyModel
  • Microsoft.Extensions.FileProviders.Abstractions
  • Microsoft.Extensions.FileProviders.Composite
  • Microsoft.Extensions.FileProviders.Physical
  • Microsoft.Extensions.FileSystemGlobbing
  • Microsoft.Extensions.Hosting
  • Microsoft.Extensions.Hosting.Abstractions
  • Microsoft.Extensions.Hosting.Systemd
  • Microsoft.Extensions.Hosting.WindowsServices
  • Microsoft.Extensions.Http
  • Microsoft.Extensions.Logging
  • Microsoft.Extensions.Logging.Abstractions
  • Microsoft.Extensions.Logging.Configuration
  • Microsoft.Extensions.Logging.Console
  • Microsoft.Extensions.Logging.Debug
  • Microsoft.Extensions.Logging.EventLog
  • Microsoft.Extensions.Logging.EventSource
  • Microsoft.Extensions.Logging.TraceSource
  • Microsoft.Extensions.Options
  • Microsoft.Extensions.Options.ConfigurationExtensions
  • Microsoft.Extensions.Options.DataAnnotations
  • Microsoft.Extensions.Primitives
  • Microsoft.NET.WebAssembly.Threading
  • Microsoft.Win32.Registry.AccessControl
  • Microsoft.Win32.SystemEvents
  • Microsoft.XmlSerializer.Generator
  • System.Collections.Immutable
  • System.ComponentModel.Composition
  • System.ComponentModel.Composition.Registration
  • System.Composition
  • System.Composition.AttributedModel
  • System.Composition.Convention
  • System.Composition.Hosting
  • System.Composition.Runtime
  • System.Composition.TypedParts
  • System.Configuration.ConfigurationManager
  • System.Diagnostics.DiagnosticSource
  • System.Diagnostics.PerformanceCounter
  • System.DirectoryServices.Protocols
  • System.Drawing.Common
  • System.Formats.Cbor
  • System.IO.Hashing
  • System.IO.Packaging
  • System.IO.Pipelines
  • System.Memory.Data
  • System.Net.Http.WinHttpHandler
  • System.Numerics.Tensors
  • System.Reflection.Context
  • System.Reflection.Metadata
  • System.Reflection.MetadataLoadContext
  • System.Resources.Extensions
  • System.Runtime.Serialization.Schema
  • System.Security.Cryptography.Cose
  • System.Security.Cryptography.Pkcs
  • System.Security.Cryptography.ProtectedData
  • System.Security.Cryptography.Xml
  • System.ServiceModel.Syndication
  • System.Text.Encoding.CodePages
  • System.Text.Json
  • System.Threading
  • System.Threading.AccessControl
  • System.Threading.Channels
  • System.Threading.RateLimiting
  • System.Threading.Tasks.Dataflow

cc @lyndaidaii@ericstj@danmoseley@jeffhandley

Author:ViktorHofer
Assignees:-
Labels:

area-Meta

Milestone:8.0.0

MSDN-WhiteKnight
MSDN-WhiteKnight reviewed Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md Outdated
@carlossanlop

carlossanlop commented Sep 1, 2023

Copy link
Copy Markdown
Contributor

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:

<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.

@lyndaidaii

lyndaidaii commented Sep 1, 2023•
edited
Loading

Copy link
Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:

<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.

There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.

carlossanlop
carlossanlop reviewed Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
This was referenced Sep 2, 2023
Merged
Merged
MSDN-WhiteKnight
MSDN-WhiteKnight reviewed Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md Outdated
@MSDN-WhiteKnightMSDN-WhiteKnight mentioned this pull request Aug 26, 2023
Closed
7 tasks
ericstjand others added 14 commits September 5, 2023 10:12
@ViktorHofer
ViktorHofer marked this pull request as ready for review September 18, 2023 13:30
ericstj
ericstj previously requested changes Sep 18, 2023
View reviewed changes

@ericstjericstj left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md Outdated
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md Outdated
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md Outdated
Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost added the needs-author-action An issue or pull request that requires more info or actions from the author. label Sep 18, 2023
@ghostghost removed the needs-author-action An issue or pull request that requires more info or actions from the author. label Sep 18, 2023
@ViktorHofer
ViktorHofer merged commit 2542302 into mainSep 18, 2023
@ViktorHofer
ViktorHofer deleted the InSourcePackageReadme branch September 18, 2023 14:12
This was referenced Sep 18, 2023
Merged
Merged
@dotnetdotnet deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas mentioned this pull request Sep 18, 2023
Closed
3 tasks
@tarekghtarekgh mentioned this pull request Oct 3, 2023
Closed
@ghostghost locked as resolved and limited conversation to collaborators Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments
+6 more reviewers
@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects

None yet

Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Add package readmes - #91210
Merged
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Sep 18, 2023
Merged
Add package readmes#91210
ViktorHofer merged 62 commits into
mainfrom 
InSourcePackageReadme
Conversation
@ViktorHofer
@ViktorHoferViktorHofer
commented
Aug 28, 2023•

edited

Loading

Copy link


Copy Markdown

Member
Contributes to #59630
One of the top customer problems that package consumers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that our packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon other tooling, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes. For a great example, please see System.Text.Json's package README. Expect to spend ~30min of your time per README. Please try to keep documentation as minimal as possible to avoid duplicating information that is already available on docs.microsoft.com.
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 18th in time for the .NET 8 RC2.
The below list is sorted by download count.
PackageStatus
Microsoft.Extensions.DependencyInjectionEdit✅
Microsoft.Extensions.LoggingEdit✅
Microsoft.Extensions.DependencyInjection.AbstractionsEdit✅
Microsoft.Extensions.HostingEdit✅
Microsoft.Extensions.Hosting.WindowsServicesEdit✅
Microsoft.Extensions.Logging.AbstractionsEdit✅
Microsoft.Extensions.HttpEdit✅
System.IO.PortsEdit✅
System.Data.OleDbEdit✅
Microsoft.Extensions.OptionsEdit✅
System.ManagementEdit✅
Microsoft.Extensions.Options.ConfigurationExtensionsEdit✅
Microsoft.Extensions.Caching.MemoryEdit✅
Microsoft.Extensions.Logging.ConsoleEdit✅
Microsoft.Extensions.Hosting.AbstractionsEdit✅
System.Text.Encoding.CodePagesEdit✅
Microsoft.Bcl.AsyncInterfacesEdit✅
System.DirectoryServices.AccountManagementEdit✅
System.SpeechEdit✅
System.DirectoryServicesEdit✅
Microsoft.Extensions.Logging.DebugEdit✅
System.Net.Http.JsonEdit✅
System.Data.OdbcEdit✅
Microsoft.Extensions.PrimitivesEdit✅
Microsoft.Bcl.Numerics (new package)Edit✅
Microsoft.Bcl.TimeProvider (new package)Edit✅
Priority 2 (.NET 8 / .NET 9)
This list is sorted alphabetically.
PackageStatus
Microsoft.Bcl.CryptographyEdit
Microsoft.Extensions.Caching.AbstractionsEdit
Microsoft.Extensions.ConfigurationEdit✅
Microsoft.Extensions.Configuration.AbstractionsEdit✅
Microsoft.Extensions.Configuration.BinderEdit✅
Microsoft.Extensions.Configuration.CommandLineEdit
Microsoft.Extensions.Configuration.EnvironmentVariablesEdit
Microsoft.Extensions.Configuration.FileExtensionsEdit
Microsoft.Extensions.Configuration.IniEdit
Microsoft.Extensions.Configuration.JsonEdit
Microsoft.Extensions.Configuration.UserSecretsEdit
Microsoft.Extensions.Configuration.XmlEdit
Microsoft.Extensions.DependencyInjection.Specification.TestsEdit
Microsoft.Extensions.DependencyModelEdit
Microsoft.Extensions.FileProviders.AbstractionsEdit
Microsoft.Extensions.FileProviders.CompositeEdit
Microsoft.Extensions.FileProviders.PhysicalEdit
Microsoft.Extensions.FileSystemGlobbingEdit
Microsoft.Extensions.Hosting.SystemdEdit
Microsoft.Extensions.Logging.ConfigurationEdit
Microsoft.Extensions.Logging.EventLogEdit✅
Microsoft.Extensions.Logging.EventSourceEdit
Microsoft.Extensions.Logging.TraceSourceEdit
Microsoft.Extensions.Options.DataAnnotationsEdit
Microsoft.NET.WebAssembly.ThreadingEdit
Microsoft.Win32.Registry.AccessControlEdit
Microsoft.Win32.SystemEventsEdit
Microsoft.XmlSerializer.GeneratorEdit
System.CodeDomEdit
System.Collections.ImmutableEdit
System.ComponentModel.CompositionEdit
System.ComponentModel.Composition.RegistrationEdit
System.CompositionEdit
System.Composition.AttributedModelEdit
System.Composition.ConventionEdit
System.Composition.HostingEdit
System.Composition.RuntimeEdit
System.Composition.TypedPartsEdit
System.Configuration.ConfigurationManagerEdit
System.Diagnostics.DiagnosticSourceEdit
System.Diagnostics.EventLogEdit✅
System.Diagnostics.PerformanceCounterEdit
System.DirectoryServices.ProtocolsEdit
System.Formats.CborEdit
System.IO.HashingEdit
System.IO.PackagingEdit
System.IO.PipelinesEdit
System.Memory.DataEdit
System.Net.Http.WinHttpHandlerEdit✅
System.Numerics.TensorsEdit
System.Reflection.ContextEdit
System.Reflection.MetadataEdit
System.Reflection.MetadataLoadContextEdit
System.Resources.ExtensionsEdit
System.Runtime.CachingEdit
System.Runtime.Serialization.SchemaEdit
System.Security.Cryptography.CoseEdit
System.Security.Cryptography.PkcsEdit
System.Security.Cryptography.ProtectedDataEdit
System.Security.Cryptography.XmlEdit
System.Security.PermissionsEdit
System.ServiceModel.SyndicationEdit
System.ServiceProcess.ServiceControllerEdit
System.Text.Encodings.WebEdit
System.Text.JsonEdit✅
System.ThreadingEdit
System.Threading.AccessControlEdit
System.Threading.ChannelsEdit✅
System.Threading.RateLimitingEdit
System.Threading.Tasks.DataflowEdit
System.Windows.ExtensionsEdit
✅ (:white_check_mark:) -> reviewed & approved
🕜 (:clock130:) -> under review
cc @lyndaidaii@ericstj@danmoseley@jeffhandley@MSDN-WhiteKnight
@ViktorHoferViktorHofer
added this to the 8.0.0 milestone
Aug 28, 2023
@ghost
ghost
commented
Aug 28, 2023

Copy link


Copy Markdown

Tagging subscribers to this area: @dotnet/area-meta

See info in area-owners.md if you want to be subscribed.
Issue Details
Contributes to #59630
One of the top customer problems that package customers are facing is lack of documentation. As such, we are driving an effort to increase the adoption and quality of NuGet package READMEs.
Ask
To lead by example and ensure that your packages have the maximum impact, we would greatly appreciate your support in increasing the adoption and quality of NuGet package READMEs.
Why
The README file is an essential part of your package as it provides important information to users and helps them understand what the package is and what it does quickly. Also, README is the first things for users when they view your package on NuGet.org and soon Visual Studio/Visual Studio Code, it is crucial for package authors to write and include high-quality READMEs for their packages.
How
This PR initializes READMEs for all the below listed packages. Please directly push to this branch and also use this PR by your POD area team to review changes.
For a great example, please see System.Text.Json's package README: https://github.com/dotnet/runtime/blob/main/src/libraries/System.Text.Json/src/PACKAGE.md
I will then backport these changes into the release/8.0 branch. The more package READMEs we add, the higher the customer impact.
Priority 1 (.NET 8 RC 2)
Our goal is to have the below list of .NET 8 packages publish with a README by September 11th in time for the .NET 8 RC2.
  •  Microsoft.Bcl.AsyncInterfaces
  •  System.CodeDom
  •  System.Data.Odbc
  •  System.Data.OleDb
  •  System.Diagnostics.EventLog
  •  System.DirectoryServices
  •  System.DirectoryServices.AccountManagement
  •  System.IO.Ports
  •  System.Management
  •  System.Net.Http.Json
  •  System.Runtime.Caching
  •  System.Security.Permissions
  •  System.ServiceProcess.ServiceController
  •  System.Speech
  •  System.Text.Encodings.Web
  •  System.Windows.Extensions
Prio 2 (.NET 8 / .NET 9)
  •  Microsoft.Bcl.Cryptography
  •  Microsoft.Bcl.Numerics
  •  Microsoft.Bcl.TimeProvider
  •  Microsoft.Extensions.Caching.Abstractions
  •  Microsoft.Extensions.Caching.Memory
  •  Microsoft.Extensions.Configuration
  •  Microsoft.Extensions.Configuration.Abstractions
  •  Microsoft.Extensions.Configuration.Binder
  •  Microsoft.Extensions.Configuration.CommandLine
  •  Microsoft.Extensions.Configuration.EnvironmentVariables
  •  Microsoft.Extensions.Configuration.FileExtensions
  •  Microsoft.Extensions.Configuration.Ini
  •  Microsoft.Extensions.Configuration.Json
  •  Microsoft.Extensions.Configuration.UserSecrets
  •  Microsoft.Extensions.Configuration.Xml
  •  Microsoft.Extensions.DependencyInjection
  •  Microsoft.Extensions.DependencyInjection.Abstractions
  •  Microsoft.Extensions.DependencyInjection.Specification.Tests
  •  Microsoft.Extensions.DependencyModel
  •  Microsoft.Extensions.FileProviders.Abstractions
  •  Microsoft.Extensions.FileProviders.Composite
  •  Microsoft.Extensions.FileProviders.Physical
  •  Microsoft.Extensions.FileSystemGlobbing
  •  Microsoft.Extensions.Hosting
  •  Microsoft.Extensions.Hosting.Abstractions
  •  Microsoft.Extensions.Hosting.Systemd
  •  Microsoft.Extensions.Hosting.WindowsServices
  •  Microsoft.Extensions.Http
  •  Microsoft.Extensions.Logging
  •  Microsoft.Extensions.Logging.Abstractions
  •  Microsoft.Extensions.Logging.Configuration
  •  Microsoft.Extensions.Logging.Console
  •  Microsoft.Extensions.Logging.Debug
  •  Microsoft.Extensions.Logging.EventLog
  •  Microsoft.Extensions.Logging.EventSource
  •  Microsoft.Extensions.Logging.TraceSource
  •  Microsoft.Extensions.Options
  •  Microsoft.Extensions.Options.ConfigurationExtensions
  •  Microsoft.Extensions.Options.DataAnnotations
  •  Microsoft.Extensions.Primitives
  •  Microsoft.NET.WebAssembly.Threading
  •  Microsoft.Win32.Registry.AccessControl
  •  Microsoft.Win32.SystemEvents
  •  Microsoft.XmlSerializer.Generator
  •  System.Collections.Immutable
  •  System.ComponentModel.Composition
  •  System.ComponentModel.Composition.Registration
  •  System.Composition
  •  System.Composition.AttributedModel
  •  System.Composition.Convention
  •  System.Composition.Hosting
  •  System.Composition.Runtime
  •  System.Composition.TypedParts
  •  System.Configuration.ConfigurationManager
  •  System.Diagnostics.DiagnosticSource
  •  System.Diagnostics.PerformanceCounter
  •  System.DirectoryServices.Protocols
  •  System.Drawing.Common
  •  System.Formats.Cbor
  •  System.IO.Hashing
  •  System.IO.Packaging
  •  System.IO.Pipelines
  •  System.Memory.Data
  •  System.Net.Http.WinHttpHandler
  •  System.Numerics.Tensors
  •  System.Reflection.Context
  •  System.Reflection.Metadata
  •  System.Reflection.MetadataLoadContext
  •  System.Resources.Extensions
  •  System.Runtime.Serialization.Schema
  •  System.Security.Cryptography.Cose
  •  System.Security.Cryptography.Pkcs
  •  System.Security.Cryptography.ProtectedData
  •  System.Security.Cryptography.Xml
  •  System.ServiceModel.Syndication
  •  System.Text.Encoding.CodePages
  •  System.Text.Json
  •  System.Threading
  •  System.Threading.AccessControl
  •  System.Threading.Channels
  •  System.Threading.RateLimiting
  •  System.Threading.Tasks.Dataflow
cc @lyndaidaii@ericstj@danmoseley@jeffhandley
Author:ViktorHofer
Assignees:-
Labels:
area-Meta
Milestone:8.0.0
MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Aug 28, 2023
View reviewed changes
Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

@carlossanlop
carlossanlop
commented
Sep 1, 2023

Copy link


Copy Markdown

Contributor
Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
@lyndaidaii
lyndaidaii
commented
Sep 1, 2023•

edited

Loading

Copy link


Copy Markdown

Is markdown going to support adding API xrefs like in dotnet-api-docs? For example, when we write markdown remarks, you can add something like:
<xref:System.IO.FileStream.Seek(System.Int64,System.IO.SeekOrigin)>

Which gets converted to a hyperlink that takes you to the FileStream.Seek method page.
There is a gap between GitHub flavor markdowns and NuGet.org. Currently we don't support it. We would like to reduce the gap. Happy to create task to take a look at this see if we could support it. Maybe use link label as workaround.
carlossanlop
carlossanlop
reviewed
Sep 1, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md

This was referenced Sep 2, 2023
 Merged

 Merged

MSDN-WhiteKnight
MSDN-WhiteKnight
reviewed
Sep 2, 2023
View reviewed changes
Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Diagnostics.EventLog/src/PACKAGE.md
Outdated

@MSDN-WhiteKnightMSDN-WhiteKnight
mentioned this pull request
Aug 26, 2023

Closed

7 tasks
ericstjand others
added 14 commits
September 5, 2023 10:12
@ViktorHofer
ViktorHofer
marked this pull request as ready for review
September 18, 2023 13:30
ericstj
ericstj
previously requested changes
Sep 18, 2023
View reviewed changes
@ericstjericstj
left a comment


Copy link


Copy Markdown

Member
Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like some issues with the packages that previously had templates. Probably the best thing to do right now is to revert the sections that aren't filled out - but save that point in a branch so that folks can resume the work after this merges.
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.CommandLine/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.EnvironmentVariables/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.FileExtensions/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Ini/src/PACKAGE.md
Comment threadsrc/libraries/Microsoft.Extensions.Configuration.Json/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Configuration.ConfigurationManager/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.Metadata/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Reflection.MetadataLoadContext/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Runtime.Caching/src/PACKAGE.md
Outdated

Comment threadsrc/libraries/System.Text.Json/src/PACKAGE.md
@ghostghost
added
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ghostghost
removed
the 
needs-author-action
An issue or pull request that requires more info or actions from the author.
label
Sep 18, 2023
@ViktorHofer
ViktorHofer
merged commit 2542302
into
mainSep 18, 2023
@ViktorHofer
ViktorHofer
deleted the

InSourcePackageReadme

branch
September 18, 2023 14:12

This was referenced Sep 18, 2023
 Merged

 Merged

@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@dotnetdotnet
deleted a comment from github-actionsBotSep 18, 2023
@JonDouglasJonDouglas
mentioned this pull request
Sep 18, 2023

Closed

3 tasks
@tarekghtarekgh
mentioned this pull request
Oct 3, 2023

Closed

@ghostghost
locked as resolved and limited conversation to collaborators
Oct 18, 2023
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.


Reviewers

@CarnaViireCarnaViireCarnaViire left review comments
@jozkeejozkeejozkee left review comments
@rojirojiroji approved these changes
@ericstjericstjericstj left review comments

+6 more reviewers

@carlossanlopcarlossanlopcarlossanlop left review comments
@danmoseleydanmoseleydanmoseley left review comments
@antonfirsovantonfirsovantonfirsov left review comments
@MSDN-WhiteKnightMSDN-WhiteKnightMSDN-WhiteKnight left review comments
@buyaa-nbuyaa-nbuyaa-n left review comments
@lyndaidaiilyndaidaiilyndaidaii left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

@ViktorHoferViktorHofer

Labels

area-Meta

Projects


None yet


Milestone

8.0.0

Development

Successfully merging this pull request may close these issues.

18 participants

@ViktorHofer@carlossanlop@lyndaidaii@CarnaViire@krwq@danmoseley@roji@antonfirsov@ericstj@tannergooding@jozkee@MSDN-WhiteKnight@buyaa-n@tarekgh@stephentoub@eiriktsarpalis@steveharter@michaelgsharp