Skip to content

Rewrite the README around a runnable quick start - #5

Merged
sadeqabuhattem merged 1 commit into
mainfrom
docs/simplify-readme
Sep 19, 2026
Merged

sadeqabuhattem merged 1 commit into
mainfrom
docs/simplify-readme

Conversation

@sadeqabuhattem

Copy link
Copy Markdown
Member

Why

New users couldn't get started from the README:

  • Install failed. Only 1.0.0-preview.1 is on NuGet, so dotnet add package DotNetBoost.Settings.Core errors with "There are no stable versions available".
  • The Quick Start couldn't run. It used an AppDbContext it never defined, had no using lines, and needed EF migrations.
  • Port 5000 fails on macOS. AirPlay Receiver holds it and answers 403.

What changed

  • README.md is 870 → ~240 lines. It opens with a one-line pitch, then a 5-minute quick start: a single-file EF Core + SQLite Program.cs plus three curl commands that change a setting while the app runs. After that:
    • reading and writing settings in your own code
    • a table for plugging in your existing database
    • an "I want to…" table linking each feature to its guide
    • the one-command Aspire demo
    • the package list
  • The anonymous-endpoints warning now sits right after the quick start instead of halfway down.
  • Reference material moved to docs/, with nothing removed. There are 13 topic pages plus an index at docs/README.md. Relative paths and cross-page anchors are fixed.
  • README links are absolute GitHub URLs, because the README is also the NuGet package readme (PackageReadmeFile) and relative links break on nuget.org.
  • --prerelease is on every install command.
  • docs/storage-providers.md now has the install commands and using lines each provider needs.
  • docs/validation.md:
    • adds the DotNetBoost.Settings.FluentValidation install step
    • corrects the "every write path" claim: Data Annotations are only enforced by the REST POST, not by SetAsync(). The code change to fix that is a separate follow-up.

Verification

I ran the quick start exactly as written in a fresh dotnet new web project against the published 1.0.0-preview.1 packages:

  • the first read returned smtp.example.com:587
  • the POST returned 204
  • the next read returned smtp.mycompany.com:2525
  • after a restart, the value was still smtp.mycompany.com:2525

Every relative link under docs/ resolves. Note that nuget.org keeps showing the old readme until the next package is published.

🤖 Generated with Claude Code

…ocs to docs/

The old Quick Start could not be followed as written: only a prerelease is on
NuGet, so `dotnet add package` without --prerelease fails, and the snippet
used an AppDbContext it never defined. The new README leads with a
single-file EF Core + SQLite app that was verified against the published
1.0.0-preview.1 packages, then links out to per-topic pages under docs/.

docs/validation.md now states that Data Annotations are only enforced by
the REST endpoint, not by SetAsync(), and adds the FluentValidation
package install step.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@sadeqabuhattem
sadeqabuhattem merged commit bc6644b into main Sep 19, 2026
10 checks passed
@sadeqabuhattem
sadeqabuhattem deleted the docs/simplify-readme branch September 19, 2026 18:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant