D2/D-readme: rewrite the stub README into a real one (closes #118, #102)#131
Merged
Conversation
The README was a 7-line stub: title, one-line description, two method signatures with single-sentence summaries. No badges, no installation section, no usage examples, no link to docs site or CHANGELOG. This rewrite, modelled on the DateTime-Extensions canonical README: - Adds the canonical badge collection (NuGet / downloads / PR build / release / License / .NET / GitHub). - Adds Installation, License, and Documentation sections with the standard link set. - Documents both public methods (`IsBetween` exclusive bounds, `IsInRange` inclusive bounds) in a comparison table, then with concrete usage examples covering int, DateTime, string, and a custom IComparable<T> type. - Calls out the null-safety contract explicitly. - Lists the actual target frameworks shipped by the csproj (net462 / netstandard2.0 / net8.0 / net10.0). The opening tagline emphasises *why* a consumer would reach for the library — "...the way you'd say them" framing — instead of just restating the namespace. Public surface unchanged; this is doc-only.
Contributor
There was a problem hiding this comment.
Pull request overview
Rewrites the repository README.md from a short stub into a fuller, consumer-facing README with badges, install instructions, documentation links, method semantics, and usage examples—aligning it with the project’s documentation/distribution needs.
Changes:
- Added badge set (NuGet, downloads, CI workflows, license, .NET, repo).
- Added installation, license, and documentation link sections.
- Added method semantics table plus usage examples, null-safety note, and target framework list.
Two Copilot findings on the README rewrite — both valid. 1. README.md L91 — Money example's CompareTo violated the IComparable<T> contract for null. The contract says any non-null value > null (CompareTo returns positive). The old code 'Amount.CompareTo(other?.Amount ?? 0m)' returned negative for negative Amount (since Amount.CompareTo(0m) is negative when Amount<0). Replaced with an explicit null check returning 1, and left a comment explaining why. 2. README.md L102 — null-safety snippet would trigger a nullable warning (CS8604) when copied into a consumer's project with <Nullable>enable</Nullable>, because IsBetween's T is non-null and maybeNull is string?. Added the null-forgiving operator '!' and a comment so the snippet copy-pastes warning-free while still demonstrating the runtime ArgumentNullException.
Chris-Wolfgang
added a commit
that referenced
this pull request
Jun 2, 2026
Fixes the two drift items found by audit (README.md handled separately in #131 / closes #118 / closes #102): - docfx_project/index.md was the unfilled DocFX landing-page template — '# Title', 'Quick Start Notes:' placeholder, and a template-comment about adding images. Rewritten using the DateTime-Extensions canonical landing-page shape: real title, about paragraph, quick-links, installation, doc-section index, and additional-resources block. - docs/setup.md had the wrong test project name in three places: the actual test project is 'tests/Wolfgang.Extensions.IComparable.Tests.Unit/...' not '.../Wolfgang.Extensions.IComparable.Tests/...'. Fixed all three references. Other markdown files (CHANGELOG, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, .github/copilot-instructions.md, .github/pull_request_template.md, docs/introduction.md, docs/getting-started.md, docs/README-FORMATTING.md, docs/RELEASE-WORKFLOW-SETUP.md, docs/WORKFLOW_SECURITY.md, docs/DOCFX-VERSION-PICKER.md) were read and found accurate — no changes needed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replaces the 7-line stub
README.mdwith a real one modelled on theDateTime-Extensions canonical README.
What was wrong
Before:
No badges. No installation block. No link to NuGet / docs site /
CHANGELOG / CONTRIBUTING. No usage examples. No null-safety contract.
No target-framework list. Just a tagline and two method signatures.
What's there now
release / License / .NET / GitHub) matching DateTime-Extensions
dotnet add packageexampleCONTRIBUTING, and
docs/setup.mdIsBetween(exclusive) vsIsInRange(inclusive) on bound semantics — the distinction is the entire
reason both methods exist, but the previous README hid it in two
prose sentences
int,DateTime,string, and a customIComparable<T>record type (Money)<TargetFrameworks>in the src csproj (
net462;netstandard2.0;net8.0;net10.0)Scope
Doc-only — no source, csproj, or workflow changes. Public surface
unchanged.
Stacked on vNext (PR #129).