O redator de changelog para mudanças disruptivas de API
Porque é que este prompt importa
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.
Para que o usamos
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]
Resultado
## 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`.
Lançar uma mudança disruptiva em uma API é trabalho de engenharia rotineiro. Comunicá-la bem é onde a maioria das equipes falha. Uma entrada de changelog que enterra a parte disruptiva em linguagem educada demais, ou um guia de migração que pula o único caso extremo que corrompe dados silenciosamente em vez de gerar erro, transforma uma mudança planejada em um simulado de incêndio para o suporte.
Este prompt impõe duas disciplinas que engenheiros costumam pular sob pressão de prazo: declarar a severidade claramente no topo, e buscar explicitamente riscos de falha silenciosa — os casos em que o código antigo continua rodando mas produz resultados errados em vez de falhar de forma visível. Essa segunda restrição é a que faz o trabalho de verdade. A maioria dos guias de migração descreve o que mudou; poucos descrevem o que quebra silenciosamente.
A estrutura (entrada de changelog, depois guia de migração com exemplos antes/depois, passos numerados e uma seção dedicada a falhas silenciosas) espelha o que equipes maduras de API em empresas como Stripe e Twilio já fazem por convenção. Este prompt torna essa estrutura repetível para equipes que não têm um redator dedicado de relações com desenvolvedores.