Add PackageReadmeFile. (#888)

* Add PackageReadmeFile.

* Update the changelog.

* Add a separate package readme.

Author: peymanr34

CHANGELOG.md

@@ -10,6 +10,7 @@
 * [UPDATE][BREAKING] Nullability is enabled for public api for .NET Core TFMs
 * [UPDATE] Migrate to slnx format for solution file
 * [UPDATE] Migrate documentation validation from build.fsproj to Roslyn code generator
+* [NEW] Added NuGet Package README file.
 
 ### 5.3.0 (October 2024)
 

src/NSubstitute/NSubstitute.csproj

@@ -19,6 +19,7 @@
     <PackageId>NSubstitute</PackageId>
     <PackageTags>mocking;mocks;testing;unit-testing;TDD;AAA</PackageTags>
     <PackageIcon>icon.png</PackageIcon>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageProjectUrl>https://nsubstitute.github.io/</PackageProjectUrl>
     <PackageLicenseExpression>BSD-3-Clause</PackageLicenseExpression>
     <RepositoryUrl>https://github.com/nsubstitute/NSubstitute</RepositoryUrl>
@@ -45,6 +46,7 @@
 
   <ItemGroup>
     <None Include="..\..\docs\images\nsubstitute-100x100.png" Pack="true" PackagePath="icon.png" Visible="false" />
+    <None Include="README.md" Pack="true" PackagePath="\" />
   </ItemGroup>
 
   <ItemGroup>

src/NSubstitute/README.md

@@ -0,0 +1,37 @@
+# NSubstitute
+
+A friendly substitute for .NET mocking libraries.
+
+Perfect for those new to testing, and for others who would just like to to get their tests written with less noise and fewer lambdas.
+
+## How to use
+
+```csharp
+// Create:
+var calculator = Substitute.For<ICalculator>();
+
+// Set a return value:
+calculator.Add(1, 2).Returns(3);
+Assert.AreEqual(3, calculator.Add(1, 2));
+
+// Check received calls:
+calculator.Received().Add(1, Arg.Any<int>());
+calculator.DidNotReceive().Add(2, 2);
+
+// Raise events
+calculator.PoweringUp += Raise.Event();
+```
+
+## Optional Roslyn analysers
+
+- For C# projects: [NSubstitute.Analyzers.CSharp](https://www.nuget.org/packages/NSubstitute.Analyzers.CSharp/)
+- For VB projects: [NSubstitute.Analyzers.VisualBasic](https://www.nuget.org/packages/NSubstitute.Analyzers.VisualBasic/)
+
+## Getting help
+
+If you have questions, feature requests or feedback on NSubstitute please [raise an issue](https://github.com/nsubstitute/NSubstitute/issues) on our project site.
+
+## More information
+
+- Visit [NSubstitute website](https://nsubstitute.github.io) for more examples and documentation.
+- Visit [NSubstitute on GitHub](https://github.com/nsubstitute/NSubstitute).