The API Breaking-Change Changelog Writer
Why this prompt matters
Vague or buried breaking-change announcements are a leading cause of support ticket floods and silent data corruption downstream — teams that skip a structured migration guide see adoption of the new format stall for months while duplicate ‘what changed?’ tickets pile up.
What we use it for
You're a platform engineer at a payments company shipping a breaking webhook schema change that will affect roughly 400 external integrations, and you need to publish a changelog entry and migration guide before the sprint ends today.
Prompt
Role: Act as a senior API platform engineer and technical writer who specializes in developer communications for breaking changes. Context: I am shipping a breaking change to an API that external developers and internal teams depend on. Here are the details: - API/endpoint affected: [API OR ENDPOINT NAME] - What is changing: [DESCRIBE THE TECHNICAL CHANGE, e.g. "the `user_id` field is being renamed to `userId`" or "authentication is moving from API keys to OAuth2"] - Why it's changing: [REASON FOR THE CHANGE] - Current version: [CURRENT API VERSION] - New version: [NEW API VERSION] - Deprecation timeline: [E.G. "old behavior supported for 90 days, removed on DATE"] - Rough number and type of affected consumers: [E.G. "~400 external integrations, mostly server-side"] Task: Produce two deliverables: 1. A changelog entry suitable for a public developer changelog page. 2. A migration guide that walks an affected developer through updating their integration step by step. Constraints: - Do not bury the breaking change under soft language. State plainly what breaks and when. - Include a severity/impact label (e.g. Breaking / Action Required) at the top of the changelog entry. - The migration guide must include at least one before/after code or request example. - Call out any silent-failure risks explicitly (places where old code keeps running but produces wrong results, rather than erroring immediately). - Keep the changelog entry under 150 words; the migration guide can be longer but must use numbered steps. - Do not invent technical details beyond what I provided in [brackets] — if something is unclear, flag it as a placeholder rather than guessing. Output Format: ## Changelog Entry [Severity label] [Date] [One-paragraph entry] ## Migration Guide ### What's changing and why [2-3 sentences] ### Before / After [code or request comparison] ### Steps to migrate [numbered list] ### Silent-failure risks [bullet list, or "None identified" if genuinely none] ### Deprecation timeline [dates and what happens at each stage]
Result
## Changelog Entry **[Breaking — Action Required]** — March 3, 2027
Webhook payloads from the `/v2/payments` endpoint now use camelCase field names (`userId`, `createdAt`, `paymentMethod`) instead of snake_case (`user_id`, `created_at`, `payment_method`), aligning with the rest of our v2 API surface. This affects all webhook consumers subscribed to payment events. The old snake_case format will continue to be sent alongside the new fields until June 1, 2027, after which snake_case fields will be removed entirely. Update your webhook handlers to read the camelCase fields before that date.
## Migration Guide
### What's changing and why We're standardizing all v2 webhook payloads on camelCase to match our REST API conventions. Payment webhooks were the last holdout using the older snake_case format from v1.
### Before / After Before: ```json {"user_id": "usr_8821", "created_at": "2027-03-01T10:00:00Z", "payment_method": "card"} ``` After: ```json {"userId": "usr_8821", "createdAt": "2027-03-01T10:00:00Z", "paymentMethod": "card", "user_id": "usr_8821", "created_at": "2027-03-01T10:00:00Z", "payment_method": "card"} ```
### Steps to migrate 1. Update your webhook handler to read `userId`, `createdAt`, and `paymentMethod` instead of the snake_case equivalents. 2. Deploy and verify your handler processes both formats correctly during the transition window (both are present until June 1, 2027). 3. Remove any code paths that reference the snake_case fields. 4. Confirm via our webhook testing console that your endpoint returns a 200 on a test payment event.
### Silent-failure risks - If your handler uses a strict schema validator that rejects unknown fields, the new camelCase fields may cause validation errors even though the payload is otherwise valid — check for `additionalProperties: false` in your schema. - Handlers that default missing fields to `null` instead of erroring could silently process payment events with `userId: null` if you update field names incorrectly, without any visible failure.
### Deprecation timeline - March 3, 2027: camelCase fields added alongside existing snake_case fields. - June 1, 2027: snake_case fields removed. Handlers not updated by this date will stop receiving `user_id`, `created_at`, and `payment_method`.
Shipping a breaking API change is routine engineering work. Communicating it well is where most teams fail. A changelog entry that buries the breaking part in polite language, or a migration guide that skips the one edge case that silently corrupts data instead of erroring, turns a planned change into a support fire drill.
This prompt forces two disciplines that engineers often skip under deadline pressure: stating the severity plainly at the top, and explicitly hunting for silent-failure risks — the cases where old code keeps running but produces wrong results rather than failing loudly. That second constraint is the one doing the real work. Most migration guides describe what changed; few describe what breaks quietly.
The structure (changelog entry, then migration guide with before/after examples, numbered steps, and a dedicated silent-failure section) mirrors what mature API teams at companies like Stripe and Twilio already do by convention. This prompt makes that structure repeatable for teams who don't have a dedicated developer relations writer on staff.