Reading PR Descriptions
5 exercises — read a realistic GitHub PR description with a breaking change note, test plan, and multiple issue references. Extract motivation, understand deployment requirements, and interpret design decisions.
Key sections in a PR description
- Summary → what changed and the one-line rationale
- Motivation → evidence of the problem (incidents, metrics, user reports)
- Breaking Change → what will break and what must be done before deploying
- How to Test → reproducible steps with expected results
- Related Issues → "Closes #N" auto-closes the issue on merge
0 / 5 completed
1 / 5
Pull Request #1024 — Migrate email delivery to SendGrid
## Pull Request #1024 — Migrate email delivery to SendGrid
**Author:** @alex_backend | **Branch:** feature/sendgrid-migration → main
**Status:** Ready for Review | **Reviewers:** @dana_infra, @priya_r
---
### Summary
Replaces the in-house SMTP relay with SendGrid for all transactional email
delivery. The current relay has no retry logic, no delivery tracking, and has
caused two incidents of silent email loss in the past 60 days.
### Motivation
Incidents INC-0441 and INC-0449 were both caused by the SMTP relay silently
dropping emails when the downstream mail server was temporarily unreachable.
Users reported not receiving password-reset and payment-confirmation emails.
SendGrid provides automatic retries with exponential back-off, webhook delivery
events, and a dashboard for real-time delivery monitoring.
### Changes Made
- Added `SendGridEmailService` implementing the existing `IEmailService` interface
- Updated `config/mail.ts` to read `SENDGRID_API_KEY` from environment
- Replaced all direct calls to `SmtpEmailService` with dependency injection via
the `EmailServiceProvider`
- Added end-to-end tests using SendGrid's sandbox mode (no real emails sent)
### Breaking Change
**Deployment note:** The environment variable `SMTP_HOST` is no longer read.
Deployers must add `SENDGRID_API_KEY` to the production `.env` before
deploying this PR, otherwise all email delivery will fail silently.
### How to Test
1. Add `SENDGRID_API_KEY=SG.test_key` and `SENDGRID_SANDBOX=true` to `.env`
2. Run `npm test -- --grep email` — all 14 email tests should pass
3. Trigger a password-reset flow in the staging environment
4. Verify delivery event appears in the SendGrid dashboard under Activity
### Screenshots
See attached: sendgrid-dashboard-activity.png (delivery event confirmed in sandbox)
### Related Issues
Closes #998 — Silent email loss with SMTP relay
Closes #1003 — Add delivery tracking for transactional emailWhat is the primary motivation for replacing the SMTP relay, according to the Motivation section?
Silent email loss during two production incidents — confirmed user impact:
The Motivation section names two specific incidents (INC-0441 and INC-0449) and describes a concrete user impact: "Users reported not receiving password-reset and payment-confirmation emails." This is the strongest possible case for a change — real users were harmed.
What makes a strong Motivation section:
The Summary says what is changing (SMTP relay → SendGrid) and hints at why. The Motivation section provides the evidence and proof that the change is necessary. A reviewer who reads only the Summary might ask "why not just fix the SMTP relay?" — the Motivation section answers that before the question is asked.
The Motivation section names two specific incidents (INC-0441 and INC-0449) and describes a concrete user impact: "Users reported not receiving password-reset and payment-confirmation emails." This is the strongest possible case for a change — real users were harmed.
What makes a strong Motivation section:
- Evidence: Specific incident numbers rather than vague "we had issues"
- Frequency: "two incidents... in the past 60 days" shows recurrence, not a one-off
- User impact: Named email types (password-reset, payment-confirmation) show the severity
- Root cause: "relay silently dropping emails when the downstream server was temporarily unreachable" explains exactly what failed
The Summary says what is changing (SMTP relay → SendGrid) and hints at why. The Motivation section provides the evidence and proof that the change is necessary. A reviewer who reads only the Summary might ask "why not just fix the SMTP relay?" — the Motivation section answers that before the question is asked.