Le rédacteur de changelog pour changements d’API cassants
Pourquoi ce prompt est important
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.
À quoi nous l'utilisons
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]
Résultat
## 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`.
Publier un changement d’API cassant est un travail d’ingénierie de routine. Bien le communiquer, c’est là que la plupart des équipes échouent. Une entrée de changelog qui enterre la partie cassante sous un langage trop poli, ou un guide de migration qui omet le seul cas limite qui corrompt silencieusement des données au lieu de générer une erreur, transforme un changement planifié en exercice d’incendie pour le support.
Ce prompt impose deux disciplines que les ingénieurs sautent souvent sous la pression des délais : indiquer clairement la sévérité dès le début, et chercher explicitement les risques d’échec silencieux — les cas où l’ancien code continue de fonctionner mais produit des résultats erronés au lieu d’échouer bruyamment. Cette seconde contrainte est celle qui fait le vrai travail. La plupart des guides de migration décrivent ce qui a changé ; peu décrivent ce qui casse silencieusement.
La structure (entrée de changelog, puis guide de migration avec exemples avant/après, étapes numérotées et une section dédiée aux échecs silencieux) reflète ce que font déjà par convention les équipes API matures d’entreprises comme Stripe et Twilio. Ce prompt rend cette structure reproductible pour les équipes qui n’ont pas de rédacteur dédié aux relations développeurs.