Skip to content

docs: overhaul README as demo-first, move reference detail into docs/ - #149

Merged
dgates82 merged 3 commits into
release/1.2.4from
docs/readme-overhaul
Sep 21, 2026
Merged

dgates82 merged 3 commits into
release/1.2.4from
docs/readme-overhaul

Conversation

@dgates82

@dgates82 dgates82 commented Sep 20, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • Rewrites README.md as demo-first: live-demo callout, a recorded auth-flow GIF, grouped feature list, and a package-ecosystem diagram/table (this template + Jwt2Fa + NotificationProviders + dgates-mock-servers)
  • Moves JWT/notification/database configuration into docs/CONFIGURATION.md, the full TODO(template) customization table into docs/CUSTOMIZING.md, and upgrade notes into docs/UPGRADING.md
  • Moves native/hot-reload backend+frontend setup, project structure, and end-to-end suite instructions into docs/LOCAL_DEV.md
  • Updates CONTRIBUTING.md and docs/DEPLOYMENT.md cross-references to match the new anchors; preserves #how-to-use-this-template, #jwt-configuration, and #database-provider at their original locations for external links
  • Builds on the variable-based deploy config from ci: move Cloud Run deploy's GCP/WIF values to Actions variables #148 (already merged into this branch) for the "Deploy your own" section

Test plan

  • Every new/updated cross-file anchor reference resolves against a real heading (18 references checked)
  • No stale references to removed anchor locations remain
  • Leftover author-specific value grep is clean (only intentional public demo/mock URLs and a YOUR_PROJECT_ID placeholder)
  • Quickstart's documented Docker Compose service names match docker-compose.yml; the exact flow (register, confirm email, log in, enable authenticator 2FA) was run end to end while recording the README GIF
  • Sonar coverage badge re-confirmed live (90.0%, gate OK) before finalizing
  • CI (API + client build/test, SonarQube quality gate, CodeQL)
  • External search for links to removed README anchors (#running-the-template-as-is, #run-with-docker, #backend-setup, #notification-senders, #upgrading-angular, #options, #upgrading, #prerequisites, #technology-stack, #features, #customizing-for-your-project): zero hits on GitHub code search for any of the 11; the dev.to writeup's only fragment link into this repo is an unrelated page-navigation anchor; all 5 sibling-repo READMEs (Jwt2Fa, NotificationProviders, dgates-mock-servers, AwsSecretsManager, dotnet-nuget-release-template) checked directly — one plain (fragment-free) repo link in dgates-mock-servers, no anchor links found anywhere

Restructures README.md around the live demo and a grouped feature list,
adds a package-ecosystem diagram and a recorded auth-flow GIF, and moves
JWT/notification/database configuration, the customization table, and
upgrade notes into docs/CONFIGURATION.md, docs/CUSTOMIZING.md, and
docs/UPGRADING.md. docs/LOCAL_DEV.md gains the native/hot-reload setup,
end-to-end suite instructions, and project structure previously in the
README. CONTRIBUTING.md and docs/DEPLOYMENT.md's cross-references are
updated to match.
Restores the Prerequisites and EF Core/MySQL facts dropped in the move to
docs/, adds the Jwt2Fa -> NotificationProviders edge to the ecosystem
diagram, links Deploy your own's step 6 to the variables it needs, marks
README.md itself as a TODO(template) customization point, fixes the demo
callout's doubled punctuation, updates the GIF alt text to match its
content, and trims a blank leading frame from the GIF.
Wraps the Angular client and .NET API in a labeled subgraph so the
diagram visually separates this repo from the extracted packages it
depends on.
@sonarqubecloud

Copy link
Copy Markdown

@dgates82
dgates82 merged commit 4875f63 into release/1.2.4 Sep 21, 2026
8 checks passed
@dgates82 dgates82 mentioned this pull request Sep 21, 2026
5 tasks done
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