دستیار نوشتن گزارش تغییرات شکننده‌ی API
چرا این پرامپت اهمیت دارد
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.
ما از آن برای چه استفاده می‌کنیم
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.
پرامپت
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]
نتیجه
## 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`.
منتشر کردن تغییرات ناسازگار (breaking change) توی API، یه کار مهندسی روتین و همیشگیه. اما رسوندنِ درست و شفافِ خبرش به بقیه، همون جاییه که بیشتر تیمها توش به مشکل می‌خورن. وقتی توی چنجلاگ بخشهای ناسازگار رو پشت جملههای تعارفی و مودبانه پنهان کنی، یا توی راهنمای مهاجرت اون حالت خاصی رو جا بندازی که به جای ارور دادن، بی سر و صدا دیتا رو خراب میکنه، یه تغییرِ از قبل برنامهریزیشده رو یهو تبدیل می‌کنی به وضعیت آمادهباش اضطراری برای تیم پشتیبانی. 🔥
این پرامپت مهندسها رو مجبور به رعایت دو تا قاعده میکنه که معمولاً زیر فشار ددلاین از زیرشون در می‌رن: اول اینکه میزان جدی بودن قضیه رو همون بالا خیلی رک و شفاف بگن، و دوم اینکه با دقت دنبال خطرات خطای خاموش (silent failure) بگردن؛ یعنی همون مواردی که کدهای قدیمی همچنان اجرا می‌شن ولی به جای ارور دادنِ واضح، بی سر و صدا نتیجهی غلط تحویل می‌دن. کار اصلی و اساسی رو هم دقیقاً همین محدودیت دوم انجام می‌ده. بیشتر راهنماهای مهاجرت میان توضیح می‌دن چی عوض شده؛ کمتر راهنمایی پیدا می‌شه که بگه چی قراره بی سر و صدا خراب بشه. ⚡
این ساختار (اول چنجلاگ، بعد راهنمای مهاجرت به همراه مثالهای قبل و بعد، مراحل شمارهگذاریشده، و یه بخش اختصاصی برای خطاهای خاموش) دقیقاً بازتاب همون کاری هست که تیمهای باتجربهی API در شرکتهایی مثل Stripe و Twilio به صورت استاندارد انجام می‌دن. این پرامپت کاری میکنه تیمهایی هم که نویسندهی اختصاصی برای ارتباط با توسعهدهندگان ندارن، بتونن همین ساختار اصولی رو همیشه تکرار کنن. 🤖