docs: enhance README and CONTRIBUTING with improved onboarding #3997

holytshirt · 2026-01-31T16:15:45Z

Summary

Enhanced README.md with improved documentation structure and usage instructions
Updated CONTRIBUTING.md with detailed build & test instructions, Docker Compose guidance, and project structure overview
Fixed documentation typos ('Licence' spelling, 'ChannelAsync' typo)
Corrected link to CONTRIBUTING.md in Copilot instructions

Changes

README.md: Expanded documentation with better onboarding guidance
CONTRIBUTING.md: Added Build & Test section, Docker Compose usage tables, project structure breakdown
docs/transports/channelfactory.md: Fixed typo
.agent_instructions/documentation.md: Updated licence comment formatting
.github/copilot-instructions.md: Fixed link reference

…e license comment formatting

…andards - Add Prerequisites section to README (targets .NET 8-10, C# 12-14) - Add "What's Next?" navigation section after basic Quick Start - Add Table of Contents to CONTRIBUTING.md for better navigation - Add "First Time Contributing?" onboarding section with quick setup guide - Fix license header documentation to use correct format (#region Licence) Co-Authored-By: Claude Sonnet 4.5 <[email protected]>

codescene-delta-analysis

No application code in the PR — skipped Code Health checks.

See analysis details in CodeScene

Quality Gate Profile: Clean Code Collective
Want more control? Customize Code Health rules or catch issues early with our IDE extension and CLI tool.

claude · 2026-01-31T16:17:13Z

PR Review: Documentation Enhancements ✅

This is an excellent documentation improvement PR! The changes significantly enhance the onboarding experience and make the project more accessible to new contributors. Here's my detailed review:

✅ Strengths

1. README.md Improvements

Excellent structure: The new README follows modern best practices with clear sections, badges, and progressive disclosure
Quick Start section: The step-by-step examples with code snippets are very helpful for new users
Multiple use cases: Good coverage of in-process and out-of-process messaging patterns
Better discoverability: Links to documentation, supported transports, and NuGet packages

2. CONTRIBUTING.md Enhancements

"First Time Contributing?" section: Great addition! Lowers the barrier to entry
Docker Compose guidance: The table with specific compose files is very practical
Table of Contents: Makes the long document navigable
Build & Test section: Clear instructions with code examples

3. Consistency Fixes

License header correction: Fixed the important detail about British spelling (Licence not License) and proper formatting (#region without space)
Link corrections: Fixed .github/copilot-instructions.md relative path
Typo fix: Corrected ChanngeAsync → ChannelAsync in channelfactory.md:930

🔍 Minor Issues & Suggestions

1. Duplicate Content in CONTRIBUTING.md

Location: CONTRIBUTING.md:239-247

There's a duplicate paragraph about TDD workflow:

- Where possible, avoid writing tests after.
  - This will not give you scope control - only writing the code required by tests.
    - You should only write the code necessary for a test to pass; do not write speculative code.
  - It will not push you to focus on design of your classes for behavior.
    - Pay attention to the usability of your class and method; it should be self-describing.
- Where possible, avoid writing tests after.
  - This will not give you scope control - only writing the code required by tests.

Recommendation: Remove the duplicate (lines 240-244).

2. File Rename Notice

Location: CONTRIBUTING.md (file rename from Contributing.md to CONTRIBUTING.md)

The rename from Contributing.md → CONTRIBUTING.md aligns with GitHub conventions. However, you may want to verify that all external links pointing to Contributing.md (with lowercase 'c') are updated. The PR already fixed .github/copilot-instructions.md, but check:

Any external documentation
GitHub wiki links
Issue templates

3. Missing Newline at End of File

Location: .agent_instructions/documentation.md:99

The file ends without a newline character. This is a minor style issue but adding one maintains consistency with Unix conventions.

📋 Specific Recommendations

README.md

Consider adding a "Contributing" section near the end that links to CONTRIBUTING.md
The "Prerequisites" section could mention specific .NET SDK versions more explicitly (e.g., "Download .NET 8+ from https://dotnet.microsoft.com/download")

CONTRIBUTING.md

In the Docker Compose section (line 364), consider adding a note about Docker Desktop memory limits for Windows/Mac users running all services
The "First Time Contributing?" section could benefit from a link to the project's Code of Conduct

Code Quality

All changes appear to be documentation-only with no code changes, so there are:

✅ No security concerns
✅ No performance implications
✅ No breaking changes
✅ No test coverage needed

🎯 Summary

Overall Assessment: This is a high-quality documentation PR that meaningfully improves the developer experience. The changes are well-thought-out, follow best practices, and make the project more accessible.

Recommendation: Approve with minor suggestions (duplicate paragraph removal)

Action Items:

Remove duplicate TDD paragraph in CONTRIBUTING.md (lines 240-244)
Add newline at end of .agent_instructions/documentation.md
(Optional) Consider the suggestions above for README/CONTRIBUTING enhancements

Great work on improving the project documentation! 🎉

iancooper

Thanks, I think this is a big improvement.

We need to fix the Post vs Publish issue, but it looks good otherwise

iancooper · 2026-02-01T13:13:53Z

README.md

+[![CodeScene Code Health](https://codescene.io/projects/32198/status-badges/code-health)](https://codescene.io/projects/32198)
+![CodeScene System Mastery](https://codescene.io/projects/32198/status-badges/system-mastery)
+
+**Brighter is a Command Dispatcher and Command Processor framework for .NET**. It enables you to build loosely coupled, maintainable applications using the Command pattern and supports both in-process and out-of-process messaging for microservices architectures.


Do you think we should x-reference Darker here, to show the two working together?

iancooper · 2026-02-01T13:14:59Z

README.md

+var commandProcessor = host.Services.GetRequiredService<IAmACommandProcessor>();
+
+// Publish to external message broker
+await commandProcessor.PublishAsync(new GreetingEvent("World"));


PostAsync here, not PublishAsync. We might want a section on events vs. commands and Publish vs Send. But we need PostAsync for the simple message example

iancooper · 2026-02-01T13:18:12Z

README.md

+- **Validation**: `[Validation]` - Validate requests before handling
+- **Custom middleware**: Create your own attributes
+
+### Outbox Pattern for Reliable Messaging


Don't know if we need to mention switch to DepositPost and dependency on transactionprovider here?

lillo42 · 2026-02-02T08:32:15Z

README.md

+    .UseExternalBus(bus =>
+    {
+        bus.UseRabbitMQ(new RmqMessagingGatewayConfiguration
+        {
+            AmqpUri = new AmqpUriSpecification(new Uri("amqp://guest:guest@localhost:5672"))
+        });
+    });


We have changed the Brighter API in V10

.AddProducers(producer => { .... });

lillo42 · 2026-02-02T08:32:38Z

README.md

+    .Subscriptions(s =>
+        s.Add<GreetingEvent>(
+            new Subscription<GreetingEvent>(
+                new SubscriptionName("greeting-subscription"),
+                new ChannelName("greeting.event"),
+                new RoutingKey("greeting.event")
+            )
+        )
+    );


We have changed the Brighter API in V10

.AddConsumers(s => ..... );

lillo42 · 2026-02-02T08:33:57Z

README.md

+// Configure policies
+builder.Services.AddBrighter()
+    .AutoFromAssemblies()
+    .Policies(p => p.Add("MyRetryPolicy", Policy.Handle<Exception>().Retry(3)));


We have changed the Brighter API in V10, I don't remember how to use it

We also should use the Resiliance Pipeline

lillo42 · 2026-02-02T08:34:21Z

README.md

+    .AutoFromAssemblies()
+    .UseExternalBus(/* configure transport */)
+    .UseOutbox(new PostgreSqlOutbox(/* configuration */));


This is the old Brighter APi

lillo42 · 2026-02-02T08:36:51Z

CONTRIBUTING.md

+
+### Quick Setup
+1. Fork and clone the repository
+2. Ensure you have .NET 8 SDK or later installed: `dotnet --version`


Suggested change

2. Ensure you have .NET 8 SDK or later installed: `dotnet --version`

2. Ensure you have .NET 10 SDK or later installed: `dotnet --version`

lillo42 · 2026-02-02T08:36:58Z

CONTRIBUTING.md

+### Quick Setup
+1. Fork and clone the repository
+2. Ensure you have .NET 8 SDK or later installed: `dotnet --version`
+3. Build the solution: `dotnet build Brighter.sln`


Suggested change

3. Build the solution: `dotnet build Brighter.sln`

3. Build the solution: `dotnet build Brighter.slnx`

holytshirt and others added 6 commits January 31, 2026 13:56

fix(docs): correct link to CONTRIBUTING.md in Copilot instructions file

313d26e

docs: update README.md with enhanced documentation usage instructions

f9de5fb

fix(docs): correct spelling of 'Licence' in CONTRIBUTING.md and updat…

69eede8

…e license comment formatting

fix(docs): correct typo in 'ChannelAsync' in channelfactory.md

6bd6fab

fix(docs): correct spelling of 'Licence' in license comment block

cee7a0d

holytshirt requested review from DevJonny, iancooper and preardon as code owners January 31, 2026 16:15

codescene-delta-analysis bot approved these changes Jan 31, 2026

View reviewed changes

iancooper reviewed Feb 1, 2026

View reviewed changes

lillo42 reviewed Feb 2, 2026

View reviewed changes

iancooper added 2 - In Progress Documentation V10.X labels Feb 2, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: enhance README and CONTRIBUTING with improved onboarding #3997

docs: enhance README and CONTRIBUTING with improved onboarding #3997

holytshirt commented Jan 31, 2026

Uh oh!

codescene-delta-analysis bot left a comment

Uh oh!

claude bot commented Jan 31, 2026

Uh oh!

iancooper left a comment

Uh oh!

iancooper Feb 1, 2026

Uh oh!

iancooper Feb 1, 2026

Uh oh!

iancooper Feb 1, 2026

Uh oh!

lillo42 Feb 2, 2026

Uh oh!

lillo42 Feb 2, 2026 •

edited

Loading

Uh oh!

lillo42 Feb 2, 2026

Uh oh!

lillo42 Feb 2, 2026

Uh oh!

lillo42 Feb 2, 2026

Uh oh!

lillo42 Feb 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	2. Ensure you have .NET 8 SDK or later installed: `dotnet --version`
	2. Ensure you have .NET 10 SDK or later installed: `dotnet --version`

	3. Build the solution: `dotnet build Brighter.sln`
	3. Build the solution: `dotnet build Brighter.slnx`

docs: enhance README and CONTRIBUTING with improved onboarding #3997

Are you sure you want to change the base?

docs: enhance README and CONTRIBUTING with improved onboarding #3997

Conversation

holytshirt commented Jan 31, 2026

Summary

Changes

Uh oh!

codescene-delta-analysis bot left a comment

Choose a reason for hiding this comment

Uh oh!

claude bot commented Jan 31, 2026

PR Review: Documentation Enhancements ✅

✅ Strengths

1. README.md Improvements

2. CONTRIBUTING.md Enhancements

3. Consistency Fixes

🔍 Minor Issues & Suggestions

1. Duplicate Content in CONTRIBUTING.md

2. File Rename Notice

3. Missing Newline at End of File

📋 Specific Recommendations

README.md

CONTRIBUTING.md

Code Quality

🎯 Summary

Action Items:

Uh oh!

iancooper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lillo42 Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lillo42 Feb 2, 2026 •

edited

Loading