(#36) Add package readme

Author: colinangusmackay

.github/PULL_REQUEST_TEMPLATE

@@ -3,7 +3,7 @@
 <!--
 Thank you for taking the time to contribute to this project.
 
-Please, fill in all the sections. 
+Please, fill in all the sections.
 Replace items surrounded by chevrons appropriately.
 -->
 
@@ -23,13 +23,14 @@ This PR addresses Issue #<issue-number>.
 
 ### Optional
 
-<!-- 
+<!--
 Depending on what the PR is for these may not be needed.
 If any of these items are not needed, then they can be removed.
 -->
 
-- [ ] I have updated the `readme.md` file
+- [ ] I have updated the repo `readme.md` file.
+- [ ] I have updated the package `readme.md` file.
 - [ ] I have updated the documentation in the docs folder.
-- [ ] I have bumped the version number in the `version.txt`
+- [ ] I have bumped the version number in the `version.txt`.
 - [ ] I have added or updated any necessary tests.
-- [ ] I have ensured that any new code is covered by tests where reasonably possible.
+- [ ] I have ensured that any new code is covered by tests where reasonably possible.

src/Stravaig.Extensions.Logging.Diagnostics/Stravaig.Extensions.Logging.Diagnostics.csproj

@@ -12,6 +12,7 @@
         <PackageIcon>stravaig-icon.png</PackageIcon>
         <PackageTags>logging testing</PackageTags>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
+        <PackageReadmeFile>readme.md</PackageReadmeFile>
 	    <Description>
             A logging provider that hooks into the .NET Logging extensions and captures
             the logs that it receives so they can be examined later by tests.
@@ -36,6 +37,10 @@
         <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
     </PropertyGroup>
 
+    <ItemGroup>
+        <None Include="readme.md" Pack="True" PackagePath="/" />
+    </ItemGroup>
+
     <ItemGroup>
         <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
     </ItemGroup>

src/Stravaig.Extensions.Logging.Diagnostics/readme.md

@@ -0,0 +1,45 @@
+# About
+
+Stravaig Log Capture is a way to capture the logs in a test and examine them to ensure they are being generated correctly.
+
+## Version & Framework support
+
+* v1.x: Supports .NET Core 3.1 & .NET 5
+* v2.x: Supports .NET 6.0, 7.0 & 8.0
+* v3.x: Supports .NET 6.0 & 8.0
+
+## Why do I want to test my logs?
+
+Checking logs in test can be beneficial for a number of reasons.
+For example, in a background service the log is effectively its user
+interface (the user being the developer or system admin whose job it
+is to monitor the correct running of background services). By verifying
+the logs in tests, you can ensure that appropriate information is being
+delivered.
+
+Logging may also exist to output audit trails for the application, and you
+need to check in tests that it is being produced correctly.
+
+## How to use
+
+For simple tests you can pass the logger into the class under test like this:
+
+```csharp
+[Test]
+public void EnsureSomeFunctionalityWorks()
+{
+    // Arrange
+    var logger = new TestCaptureLogger<ServiceClass>();
+    var service = new ServiceClass(logger);
+    
+    // Act
+    service.DoSomething();
+    
+    // Assert
+    var logs = logger.GetLogs();
+    logs.Count.ShouldBe(1);
+    logs[0].OriginalMessage.ShouldBe("Did something.");
+}
+```
+
+For more details on more complex scenarios, see the full documentation at https://stravaig-projects.github.io/Stravaig.Extensions.Logging.Diagnostics/