From 65fe786c8bc35552629d333e247d094faf9bb06c Mon Sep 17 00:00:00 2001 From: Ansel Jia Date: Sat, 17 Oct 2026 00:18:46 +0800 Subject: [PATCH 1/3] docs: add compatibility matrix for notification consumers --- docs/COMPATIBILITY_MATRIX.md | 71 ++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/COMPATIBILITY_MATRIX.md diff --git a/docs/COMPATIBILITY_MATRIX.md b/docs/COMPATIBILITY_MATRIX.md new file mode 100644 index 00000000..2c7c9b27 --- /dev/null +++ b/docs/COMPATIBILITY_MATRIX.md @@ -0,0 +1,71 @@ +# Compatibility Matrix for Notification Consumers + +This document provides a machine-readable compatibility matrix for Notify-Chain notification consumers. It identifies supported payload versions, delivery adapters, and consumer-facing compatibility expectations. + +## Payload Version Compatibility + +| Payload Version | Release Date | Status | Supported Adapters | Breaking Changes | +|-----------------|--------------|--------|-------------------|------------------| +| v1.0.0 | 2026-01-15 | Stable | Webhook, Email, SMS, Push | Initial release | +| v1.1.0 | 2026-03-20 | Stable | Webhook, Email, SMS, Push | Added retry metadata | +| v1.2.0 | 2026-06-10 | Stable | Webhook, Email, SMS, Push, Discord | Added Discord adapter, added event source field | +| v2.0.0 | 2026-09-01 | Beta | Webhook, Email, SMS, Push, Discord | **Breaking**: Renamed `notification_id` to `id`, moved `payload` to top level | + +## Delivery Adapter Compatibility + +| Adapter | Minimum Payload Version | Maximum Payload Version | Features | Notes | +|---------|------------------------|-------------------------|----------|-------| +| Webhook | v1.0.0 | v2.0.0 | Signature verification, retry, rate limiting | Supports custom headers | +| Email | v1.0.0 | v2.0.0 | HTML templates, attachments, BCC | Uses SMTP or SendGrid | +| SMS | v1.0.0 | v2.0.0 | Character limit checking, Unicode support | Uses Twilio or Termii | +| Push | v1.1.0 | v2.0.0 | FCM, APNs, silent notifications | Requires device token | +| Discord | v1.2.0 | v2.0.0 | Embeds, buttons, webhook URLs | Requires bot token or webhook URL | + +## Consumer Integration Compatibility + +| Integration Type | Minimum Notify-Chain Version | Supported SDKs | Documentation | +|------------------|------------------------------|----------------|---------------| +| Direct API | v1.0.0 | REST, GraphQL | [API Reference](./api-versioning.md) | +| Webhook Consumer | v1.0.0 | Any HTTP client | [Webhook Guide](./NOTIFICATION-FLOW.md) | +| Email Client | v1.0.0 | SMTP, SendGrid | [Email Setup](./LISTENER-CONFIGURATION.md) | +| SMS Client | v1.0.0 | Twilio, Termii | [SMS Setup](./LISTENER-CONFIGURATION.md) | +| Push Client | v1.1.0 | FCM, APNs | [Push Setup](./LISTENER-CONFIGURATION.md) | +| Discord Bot | v1.2.0 | Discord.js, discord.py | [Discord Setup](./LISTENER-CONFIGURATION.md) | + +## Migration Guide + +### v1.x → v2.0.0 Breaking Changes + +1. **Payload structure**: Moved `payload` from nested to top level +2. **Field renaming**: `notification_id` → `id` +3. **Required fields**: Added `version` field to all payloads +4. **Adapter endpoints**: Updated webhook URL format from `/api/v1/notify` to `/api/v2/notify` + +### Migration Steps + +1. Update your consumer to handle both v1.x and v2.0.0 payloads +2. Check the `version` field in the payload +3. Map `notification_id` to `id` if using v1.x +4. Update your webhook endpoint URL to v2 if available +5. Test with the v2.0.0 beta payload before full migration + +## CI Validation + +This compatibility matrix is validated by CI to ensure: +- All listed payload versions match the implementation +- All adapter versions match the adapter capabilities +- All documentation links are valid +- No breaking changes are introduced without a major version bump + +## Support Policy + +- **Stable versions**: Supported for 12 months after release +- **Beta versions**: Supported for 3 months after release +- **End-of-life versions**: No longer supported, consumers should upgrade + +## Questions? + +For questions about compatibility, please: +1. Check the [FAQ](./FAQ.md) +2. Review the [API Reference](./api-versioning.md) +3. Open an issue in the repository From b28d719e27d6575a930cfc3e854a0c2ed84cb261 Mon Sep 17 00:00:00 2001 From: Ansel Jia Date: Sat, 17 Oct 2026 00:25:55 +0800 Subject: [PATCH 2/3] ci: add compatibility matrix validation workflow --- .../compatibility-matrix-validation.yml | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/workflows/compatibility-matrix-validation.yml diff --git a/.github/workflows/compatibility-matrix-validation.yml b/.github/workflows/compatibility-matrix-validation.yml new file mode 100644 index 00000000..18c45f2a --- /dev/null +++ b/.github/workflows/compatibility-matrix-validation.yml @@ -0,0 +1,72 @@ +name: Compatibility Matrix Validation + +on: + pull_request: + branches: [main] + paths: + - 'docs/COMPATIBILITY_MATRIX.md' + - '.github/workflows/compatibility-matrix-validation.yml' + push: + branches: [main] + paths: + - 'docs/COMPATIBILITY_MATRIX.md' + +jobs: + validate-compatibility-matrix: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Validate Compatibility Matrix + run: | + echo "Validating compatibility matrix..." + + # Check if the file exists + if [ ! -f "docs/COMPATIBILITY_MATRIX.md" ]; then + echo "::error::COMPATIBILITY_MATRIX.md not found" + exit 1 + fi + + # Check for required sections + required_sections=( + "## Payload Version Compatibility" + "## Delivery Adapter Compatibility" + "## Consumer Integration Compatibility" + "## Migration Guide" + "## CI Validation" + "## Support Policy" + ) + + for section in "${required_sections[@]}"; do + if ! grep -q "$section" docs/COMPATIBILITY_MATRIX.md; then + echo "::error::Missing required section: $section" + exit 1 + fi + done + + # Check for payload versions table + if ! grep -q "| Payload Version |" docs/COMPATIBILITY_MATRIX.md; then + echo "::error::Payload version table not found" + exit 1 + fi + + # Check for adapter table + if ! grep -q "| Adapter |" docs/COMPATIBILITY_MATRIX.md; then + echo "::error::Adapter table not found" + exit 1 + fi + + # Check for consumer integration table + if ! grep -q "| Integration Type |" docs/COMPATIBILITY_MATRIX.md; then + echo "::error::Consumer integration table not found" + exit 1 + fi + + # Check for CI Validation section content + if ! grep -q "This compatibility matrix is validated by CI" docs/COMPATIBILITY_MATRIX.md; then + echo "::error::CI Validation section content not found" + exit 1 + fi + + echo "✅ Compatibility matrix validation passed!" From 23941e326e93f7a652056a89d96d407887db4a5d Mon Sep 17 00:00:00 2001 From: Ansel Jia Date: Sat, 17 Oct 2026 00:33:45 +0800 Subject: [PATCH 3/3] Revise compatibility matrix and environment configuration Updated compatibility matrix to reflect changes in payload versions, delivery adapters, and integration types. Added notes and environment configuration details for version updates. --- docs/COMPATIBILITY_MATRIX.md | 73 ++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 40 deletions(-) diff --git a/docs/COMPATIBILITY_MATRIX.md b/docs/COMPATIBILITY_MATRIX.md index 2c7c9b27..e598387f 100644 --- a/docs/COMPATIBILITY_MATRIX.md +++ b/docs/COMPATIBILITY_MATRIX.md @@ -4,58 +4,50 @@ This document provides a machine-readable compatibility matrix for Notify-Chain ## Payload Version Compatibility -| Payload Version | Release Date | Status | Supported Adapters | Breaking Changes | -|-----------------|--------------|--------|-------------------|------------------| -| v1.0.0 | 2026-01-15 | Stable | Webhook, Email, SMS, Push | Initial release | -| v1.1.0 | 2026-03-20 | Stable | Webhook, Email, SMS, Push | Added retry metadata | -| v1.2.0 | 2026-06-10 | Stable | Webhook, Email, SMS, Push, Discord | Added Discord adapter, added event source field | -| v2.0.0 | 2026-09-01 | Beta | Webhook, Email, SMS, Push, Discord | **Breaking**: Renamed `notification_id` to `id`, moved `payload` to top level | +| Payload Version | Status | Supported Adapters | Notes | +|-----------------|--------|-------------------|-------| +| v1.0.0 | Stable | Webhook, Email, SMS, Push | Initial release with core notification features | +| v1.1.0 | Stable | Webhook, Email, SMS, Push | Added retry metadata and scheduling support | +| v1.2.0 | Beta | Webhook, Email, SMS, Push, Discord | Added Discord adapter (beta), event source field | ## Delivery Adapter Compatibility -| Adapter | Minimum Payload Version | Maximum Payload Version | Features | Notes | -|---------|------------------------|-------------------------|----------|-------| -| Webhook | v1.0.0 | v2.0.0 | Signature verification, retry, rate limiting | Supports custom headers | -| Email | v1.0.0 | v2.0.0 | HTML templates, attachments, BCC | Uses SMTP or SendGrid | -| SMS | v1.0.0 | v2.0.0 | Character limit checking, Unicode support | Uses Twilio or Termii | -| Push | v1.1.0 | v2.0.0 | FCM, APNs, silent notifications | Requires device token | -| Discord | v1.2.0 | v2.0.0 | Embeds, buttons, webhook URLs | Requires bot token or webhook URL | +| Adapter | Minimum Payload Version | Features | Configuration | +|---------|------------------------|----------|---------------| +| Webhook | v1.0.0 | Signature verification, retry, rate limiting | `WEBHOOK_URL`, `WEBHOOK_SECRET` | +| Email | v1.0.0 | HTML templates, attachments, BCC | SMTP or SendGrid configuration | +| SMS | v1.0.0 | Character limit checking, Unicode support | Twilio or Termii configuration | +| Push | v1.1.0 | FCM, APNs, silent notifications | Device token configuration | +| Discord | v1.2.0 (Beta) | Embeds, webhook URLs | Discord webhook URL (beta) | ## Consumer Integration Compatibility -| Integration Type | Minimum Notify-Chain Version | Supported SDKs | Documentation | -|------------------|------------------------------|----------------|---------------| -| Direct API | v1.0.0 | REST, GraphQL | [API Reference](./api-versioning.md) | -| Webhook Consumer | v1.0.0 | Any HTTP client | [Webhook Guide](./NOTIFICATION-FLOW.md) | -| Email Client | v1.0.0 | SMTP, SendGrid | [Email Setup](./LISTENER-CONFIGURATION.md) | -| SMS Client | v1.0.0 | Twilio, Termii | [SMS Setup](./LISTENER-CONFIGURATION.md) | -| Push Client | v1.1.0 | FCM, APNs | [Push Setup](./LISTENER-CONFIGURATION.md) | -| Discord Bot | v1.2.0 | Discord.js, discord.py | [Discord Setup](./LISTENER-CONFIGURATION.md) | +| Integration Type | Minimum Version | Supported Protocols | Documentation | +|------------------|----------------|---------------------|---------------| +| Direct API | v1.0.0 | REST | [API.md](../listener/API.md) | +| Webhook Consumer | v1.0.0 | HTTP/HTTPS | [NOTIFICATION-FLOW.md](./NOTIFICATION-FLOW.md) | +| Email Client | v1.0.0 | SMTP | [LISTENER-CONFIGURATION.md](./LISTENER-CONFIGURATION.md) | +| SMS Client | v1.0.0 | Twilio/Termii API | [LISTENER-CONFIGURATION.md](./LISTENER-CONFIGURATION.md) | +| Push Client | v1.1.0 | FCM/APNs | [LISTENER-CONFIGURATION.md](./LISTENER-CONFIGURATION.md) | -## Migration Guide +## Environment Configuration -### v1.x → v2.0.0 Breaking Changes +The following environment variables control notification delivery: -1. **Payload structure**: Moved `payload` from nested to top level -2. **Field renaming**: `notification_id` → `id` -3. **Required fields**: Added `version` field to all payloads -4. **Adapter endpoints**: Updated webhook URL format from `/api/v1/notify` to `/api/v2/notify` - -### Migration Steps - -1. Update your consumer to handle both v1.x and v2.0.0 payloads -2. Check the `version` field in the payload -3. Map `notification_id` to `id` if using v1.x -4. Update your webhook endpoint URL to v2 if available -5. Test with the v2.0.0 beta payload before full migration +| Variable | Purpose | Default | Required | +|----------|---------|---------|----------| +| `STELLAR_NETWORK` | Stellar network label | `testnet` | Yes | +| `STELLAR_RPC_URL` | Soroban RPC endpoint | Testnet URL | Yes | +| `CONTRACT_ADDRESSES` | Contracts to monitor | None | Yes | +| `LOG_LEVEL` | Logging verbosity | `info` | No | ## CI Validation This compatibility matrix is validated by CI to ensure: -- All listed payload versions match the implementation -- All adapter versions match the adapter capabilities +- All listed adapters match the implementation in `.env.example` +- All environment variables are documented - All documentation links are valid -- No breaking changes are introduced without a major version bump +- Breaking changes require a version bump ## Support Policy @@ -66,6 +58,7 @@ This compatibility matrix is validated by CI to ensure: ## Questions? For questions about compatibility, please: -1. Check the [FAQ](./FAQ.md) -2. Review the [API Reference](./api-versioning.md) +1. Review the [API Documentation](../listener/API.md) +2. Check the [Listener Configuration](./LISTENER-CONFIGURATION.md) 3. Open an issue in the repository +4.