Automate Breaking Changes Documentation with ChatGPT
Documenting breaking changes is critical but time-consuming. Use these expert-crafted ChatGPT prompts to instantly generate clear, concise, and user-friendly documentation for your API or software updates. Streamline your release process, reduce user friction, and ensure your team communicates changes effectively.
Feed in a code diff to get a high-level summary of potential breaking changes for an API.
Analyze the following code diff between version [v1.0.0] and [v1.1.0] and identify all potential breaking changes for consumers of this API. For each change, list the affected component (e.g., endpoint, function, data model), a brief description of the change, and a severity rating (High, Medium, Low).
Code Diff:...
Document Endpoint Rename
Create a clear breaking change notice for when an API endpoint's path has been changed.
Write a breaking change documentation entry for an API endpoint rename.
Old Endpoint: `[e.g., /api/v1/users]`
New Endpoint: `[e.g., /api/v2/profiles]`...
Announce Parameter Removal
Draft a notice for the removal of a required or optional parameter from an API endpoint.
Generate a breaking change notice for the removal of a parameter from an API endpoint.
Endpoint: `[e.g., POST /api/v1/orders]`
Removed Parameter: `[e.g., customer_email]`...
Explain Response Field Change
Document a change in the data type or name of a field in an API response object.
Create a breaking change entry for a modified field in an API response.
Endpoint: `[e.g., GET /api/v1/products/{id}]`
Field Name: `[e.g., price]`...
Deprecate Authentication Method
Write a formal deprecation and breaking change notice for an old authentication method.
Draft a comprehensive breaking change announcement for the deprecation of an authentication method.
Deprecated Method: `[e.g., API Key in query parameter]`
New Method: `[e.g., OAuth 2.0 Bearer Token in Authorization header]`...
Draft Simple Migration Steps
Create a step-by-step migration guide for a straightforward breaking change.
Based on this breaking change: "[Describe the breaking change, e.g., The `getUser` function now returns a promise instead of a value directly]", generate a simple, step-by-step migration guide for developers. Include a 'Before' code example and an 'After' code example using async/await.
Outline Complex Migration Guide
Structure a detailed migration guide for a complex change involving multiple steps.
Outline a migration guide for a complex breaking change where we are moving from [Old System/Library, e.g., a custom state management solution] to [New System/Library, e.g., Redux Toolkit]. The guide should include sections for:
1. Prerequisites
2. Step-by-step code modification instructions...
Summarize Impact on User Segments
Analyze a list of breaking changes and summarize the impact on different user segments.
Given the following list of breaking changes, summarize the potential impact on these user segments: [e.g., Frontend Developers, Backend Developers, Data Analysts].
Breaking Changes:...
Draft Release Notes Summary
Condense a technical list of breaking changes into a high-level summary for release notes.
Convert the following technical breaking change descriptions into a user-friendly summary suitable for the "Breaking Changes" section of our main release notes. Use a friendly but professional tone.
Technical Details:...
Compose Developer Email Announcement
Draft an email to developers announcing upcoming critical breaking changes.
Write a proactive email to our developer community about upcoming critical breaking changes in our API version [e.g., v3.0]. The email should:
1. Have a clear subject line (e.g., "Action Required: Upcoming Breaking Changes in Our API").
2. Briefly explain the reason for the changes (e.g., performance and security enhancements)....
Create FAQ for Breaking Changes
Create a list of frequently asked questions based on a set of breaking changes.
Based on the following breaking change: "[Describe the change, e.g., We are deprecating our XML response format in favor of JSON exclusively]", generate a list of 5 potential FAQs that developers might have. For each question, provide a clear and concise answer.
Document SDK Method Change
Document a breaking change in a software development kit (SDK) method signature.
Write a breaking change note for an SDK method signature change.
Language: `[e.g., Python]`
SDK: `[e.g., my-company-sdk]`...
Explain Error Code/Message Change
Document changes to API error codes or the structure of error responses.
Generate a breaking change notice for a change in our API error handling.
Change Description: `[e.g., We are consolidating HTTP 400 and 422 errors. All validation errors will now return HTTP 400 with a detailed error object.]`
Old Behavior: `[e.g., Missing 'email' field returned a 422.]`...
Announce Required Dependency Update
Inform users of a breaking change caused by a required update to an underlying dependency.
Our library, `[e.g., DataProcessor v2.0]`, now requires an updated version of a core dependency. Draft a breaking change notice explaining this.
Dependency: `[e.g., Pandas]`
Old Required Version: `[e.g., >=1.0]`...
Document Config File Change
Explain a breaking change in the structure or location of a required configuration file.
Write a breaking change notice for a change in our application's configuration file.
Old file format/key: `[e.g., A YAML key 'database_url']`
New file format/key: `[e.g., A nested TOML object [database] with keys 'host', 'port', 'user']`...
Simplify Jargon for Announcement
Rewrite a technical breaking change description into simpler language for a broader audience.
Rewrite the following technical description of a breaking change into clear, simple language that a less technical project manager could understand. Focus on the 'what' and 'why' from a user perspective.
Technical Text: "We have refactored the authentication service to use JWTs with RS256 signing instead of HS256, deprecating the shared secret model. This necessitates an update to the token validation logic in all client integrations."
Format as Changelog Entry
Take a description of a breaking change and format it for a standard CHANGELOG.md file.
Format the following information into a standard entry under a '### Breaking Changes' section in a CHANGELOG.md file.
Information: The `calculate_shipping` function no longer accepts `country_code` as a string. It now requires a `region_id` integer. This was done to support complex international shipping rules. Developers must map their country codes to our new region IDs.
Create Deprecation Timeline
Generate a clear timeline for a feature or endpoint that is being deprecated.
Create a clear, timeline-based announcement for the deprecation of the `/api/v1/legacy-reports` endpoint.
- Announcement Date: `[Today's Date]`
- Brownout Period Start (endpoint returns errors intermittently): `[e.g., 3 months from now]`...
Document Permission Model Change
Explain a breaking change to the user permission or authorization model.
Write a breaking change notice for a change in our application's permission model.
Old Model: `[e.g., A single 'admin' boolean flag on the user object.]`
New Model: `[e.g., Role-based access control (RBAC) with roles like 'viewer', 'editor', 'admin'.]`...
Announce Data Model Removal
Document the complete removal of a data model or database table that was previously accessible.
Draft a breaking change announcement for the complete removal of the `[e.g., UserEvents]` data model from our public API.
Reason: `[e.g., It has been replaced by the more comprehensive 'AuditLogs' model which provides better performance and detail.]`
Action Required: `[e.g., All integrations querying the UserEvents model must be updated to use the new AuditLogs model.]`...
Document CLI Command Change
Create a breaking change notice for a command-line interface (CLI) tool.
Write a breaking change notice for a CLI command.
Old Command: `[e.g., my-cli deploy --path /src]`
New Command: `[e.g., my-cli push --source /src]`...
Announce Versioning Scheme Change
Inform users about a change in the product's versioning scheme (e.g., moving to SemVer).
Draft an announcement explaining that our product is changing its versioning scheme.
Old Scheme: `[e.g., Date-based versions like 2024.03.1]`
New Scheme: `[e.g., Semantic Versioning (Major.Minor.Patch)]`...
Draft Internal Slack Announcement
Write a concise Slack message for internal teams (e.g., support, sales) about a breaking change.
Draft a concise Slack message for our internal #customer-support channel about an upcoming breaking change. Translate the technical details into customer impact.
Technical Change: The 'export_to_csv' API endpoint will now be asynchronous and return a job ID instead of the file directly....
Create 'Before & After' Snippets
Create clear 'Before' and 'After' code snippets for a specific breaking change.
Generate 'Before' and 'After' code snippets in [language, e.g., JavaScript] to illustrate the following breaking change: The function `fetchData(callback)` has been updated to return a Promise and no longer accepts a callback.
The 'Before' snippet should use the callback pattern. The 'After' snippet should use the `.then()` or `async/await` pattern.
Assess Risk of a Breaking Change
Analyze a proposed breaking change and outline its potential risks and mitigation strategies.
Act as a principal engineer. Analyze the following proposed breaking change and provide a risk assessment.
Proposed Change: "Change the primary key for the 'users' table from an integer to a UUID to better support distributed systems."...
Brainstorm Alternatives to a Breaking Change
Propose alternative, non-breaking solutions to achieve a goal that would otherwise require a breaking change.
We need to add new information to our `/v1/products` API response, but adding new required fields would be a breaking change. The goal is to [describe goal, e.g., ensure all products have a 'region' field]. Brainstorm 3 alternative, non-breaking approaches to achieve this. For each alternative, list its pros and cons.
Turn these prompts into a reusable workspace
Save your favourite prompts once, reuse them with Alt+P, keep a live Table of Contents of long chats, and export conversations when you're done.
