feat(docs): add CompatibilityTestBot and document webhook deduplication differences

[neil-pozetroninc]

Summary

This PR adds CompatibilityTestBot and comprehensive documentation explaining the critical behavioral difference between Probot (Node.js) and ProbotSharp regarding webhook deduplication.

Key Changes:

• ✅ New CompatibilityTestBot example that disables idempotency middleware
• ✅ Comprehensive documentation updates across 6 documentation files
• ✅ Migration guide Section 7 explaining the deduplication difference
• ✅ Updated comparison table in main README

Problem Statement

Probot (Node.js) does NOT automatically deduplicate webhooks by delivery ID. The application is responsible for tracking processed delivery IDs and implementing deduplication logic.

ProbotSharp takes a more opinionated approach with built-in deduplication via UseIdempotency() middleware (enabled by default in all examples).

This critical behavioral difference was previously undocumented in:

• Migration guide (Probot-to-ProbotSharp-Guide.md)
• Main README comparison table
• Configuration best practices
• Operational guidance

Solution

1. CompatibilityTestBot Example (6 new files, 940 lines)

• examples/CompatibilityTestBot/ - Complete test application
• Disables UseIdempotency() to match Probot behavior
• Tracks all webhook deliveries including duplicates
• Provides HTTP API for integration testing
• Comprehensive README with troubleshooting

Features:

• HTTP-based integration testing against real server process
• TestEventTracker to verify webhook delivery processing
• Demonstrates proper ASP.NET Core Minimal API patterns
• Production-ready configuration with clear documentation

2. Documentation Updates (154 lines added across 6 files)

Probot-to-ProbotSharp-Guide.md:

• New Section 7 (~120 lines) documenting deduplication difference
• Code examples showing both Probot and ProbotSharp behavior
• Configuration examples for InMemory, Redis, and Database providers
• Clear guidance on when to enable/disable idempotency

README.md:

• Added row to comparison table highlighting webhook deduplication

Architecture.md:

• Contextualized idempotency strategy as difference from Probot
• Updated ADR-002 with Probot comparison note

AdapterConfiguration.md:

• Added callout explaining Probot difference
• Clarified how to disable for Probot-compatible behavior

ConfigurationBestPractices.md:

• New middleware configuration section
• Trade-offs of enabling/disabling idempotency
• Cross-references to related documentation

Operations.md:

• Added idempotency metrics section
• Guidance on monitoring duplicate delivery rates
• Context about expected duplicate scenarios

Impact

For Developers:

• Clear understanding of behavioral difference from Probot
• Ability to choose appropriate behavior for their use case
• Better integration testing capabilities
• Reduced confusion during migration

For Documentation:

• Comprehensive coverage of idempotency difference
• Cross-referenced sections for easy navigation
• Production-ready examples with clear guidance

Testing

• ✅ Build succeeded (0 errors, StyleCop warnings expected)
• ✅ All pre-commit hooks passed:
  • kubeconform: ✓
  • verify-local-links: ✓ (406 valid links)
  • verify-github-links: ✓ (27 verified)
  • verify-markdown-code: ✓ (17 verified)

Files Changed

New Files (6):

• examples/CompatibilityTestBot/CompatibilityTestApp.cs (315 lines)
• examples/CompatibilityTestBot/CompatibilityTestBot.csproj (22 lines)
• examples/CompatibilityTestBot/Program.cs (193 lines)
• examples/CompatibilityTestBot/README.md (267 lines)
• examples/CompatibilityTestBot/TestEventTracker.cs (84 lines)
• examples/CompatibilityTestBot/appsettings.json (59 lines)

Modified Files (6):

• README.md (1 line added)
• docs/AdapterConfiguration.md (3 lines added)
• docs/Architecture.md (7 lines added)
• docs/ConfigurationBestPractices.md (21 lines added)
• docs/Operations.md (7 lines added)
• docs/Probot-to-ProbotSharp-Guide.md (115 lines added)

Total: 12 files changed, 1,094 insertions(+)

Related Issues

This addresses the documentation gap identified regarding webhook deduplication behavioral differences between Probot and ProbotSharp.

---

Ready for Review ✅