Master this essential documentation concept
An update to a software product or API that is incompatible with previous versions, meaning code or configurations written for older versions will stop working correctly after the change.
An update to a software product or API that is incompatible with previous versions, meaning code or configurations written for older versions will stop working correctly after the change.
When your engineering team ships a breaking change, the knowledge transfer often happens in real time — a quick all-hands recording, a sprint retrospective video, or a recorded architecture review where someone walks through exactly what broke and why. That context is genuinely valuable, but it has a short shelf life when it lives only as a video file.
The problem surfaces weeks later. A developer onboarding to the project searches your internal docs for why a deprecated endpoint was removed, or a technical writer needs to update the migration guide but can't remember which recording covered the rollback behavior. Scrubbing through a 45-minute meeting to find a two-minute explanation of a breaking change is a real productivity drain — and it often means that critical context simply gets skipped.
Converting those recordings into searchable documentation changes how your team handles this. Instead of a timestamp buried in a video, the specific reasoning behind a breaking change becomes a retrievable, linkable section that developers and writers can reference directly. You can surface the "why" alongside the "what" in your existing docs, making migration guides and changelogs more accurate without requiring someone to re-watch every relevant recording.
If your team regularly documents API updates, deprecations, or version migrations through recorded sessions, see how a video-to-documentation workflow can help keep that knowledge accessible.
A platform team renames /api/v1/user/profile to /api/v2/accounts/me and changes the JSON response shape. Dozens of third-party integrators receive 404 errors and malformed data with no advance warning or migration path documented.
A formally documented breaking change notice communicates the exact endpoint deprecation timeline, the diff between old and new response schemas, and provides side-by-side code examples showing how to update client calls.
["Create a dedicated 'Breaking Changes' section in the API changelog, tagging the change with a severity label (e.g., BREAKING) and the affected endpoint /api/v1/user/profile.", "Publish a schema diff table comparing the v1 response fields (e.g., 'user_name', 'profile_pic') against v2 equivalents (e.g., 'username', 'avatar_url'), explicitly noting removed or renamed fields.", 'Add a migration code block in both cURL and JavaScript showing the before/after request URL, headers, and response parsing logic.', "Set a deprecation date 90 days out, configure the v1 endpoint to return a 'Deprecation' HTTP response header pointing to the migration guide URL, and send direct email notices to registered API consumers."]
Integrators receive structured advance notice with actionable code examples, reducing support tickets related to the migration by an estimated 70% and ensuring zero-surprise cutover on the deprecation date.
The data engineering team changes a widely-used SDK method from client.upload(file, bucket) to client.upload(source=file, destination=bucket), making positional arguments fail silently or raise TypeErrors in production pipelines.
A breaking change entry in the SDK's CHANGELOG.md and updated docstrings explicitly flags the old positional signature as removed, provides the new keyword-argument syntax, and includes a codemod script to automate the fix across codebases.
['Add a BREAKING CHANGE block at the top of the CHANGELOG.md entry for the new SDK version, specifying the method name, the old signature, and the new required keyword-argument signature.', "Update the SDK's docstring and type hints for the upload() method to reflect the new signature, and add a DeprecationWarning in the previous minor version that fires when positional arguments are detected.", "Publish a migration guide page with a before/after code snippet and a downloadable Python codemod script using the 'libcst' library to automatically refactor old call sites.", 'Bump the SDK version to a new major version (e.g., 2.0.0) following semantic versioning, ensuring package managers like pip do not auto-upgrade consumers past the breaking boundary.']
Library consumers can run the provided codemod to fix all call sites automatically, and the semantic version bump prevents unintentional upgrades, resulting in a smooth transition with minimal production incidents.
The platform team drops the legacy 'full_name' column from the users table after splitting it into 'first_name' and 'last_name', causing three microservices that still SELECT full_name to throw SQL errors in production.
A breaking change runbook documents the column removal, the SQL migration script, a compatibility view that temporarily bridges old queries, and a service-by-service checklist for dependent teams to update their ORM models before the column is dropped.
["Publish an internal breaking change notice in the team wiki specifying the table name, the column being dropped ('full_name'), the target drop date, and the list of known dependent services identified via grep across repositories.", "Create a temporary SQL compatibility view (CREATE VIEW users_compat AS SELECT *, CONCAT(first_name, ' ', last_name) AS full_name FROM users) and document it as a short-term bridge, with a hard removal date 30 days after the column drop.", 'Provide ORM migration snippets for SQLAlchemy and Django models showing how to replace the full_name field mapping with a computed property combining first_name and last_name.', 'Require each dependent service team to check off their service in a shared migration tracking document before the drop date, and run a final automated query to confirm no active queries reference the column.']
All dependent services are updated before the column is dropped, the compatibility view prevents any production downtime during the transition window, and the tracking document provides an auditable record of migration completion.
A DevOps platform renames the pipeline configuration key 'build_image' to 'runner_image' in its YAML schema, causing hundreds of existing pipeline definitions to fail validation silently or produce cryptic error messages with no guidance.
A breaking change notice in the platform's release notes, combined with an updated JSON Schema and a migration linter, guides teams to rename the key and validates their pipeline files before deployment.
["Add a prominent BREAKING CHANGE banner to the platform's release notes for the affected version, listing the exact YAML key rename from 'build_image' to 'runner_image' with a before/after YAML snippet.", "Update the platform's published JSON Schema to mark 'build_image' as deprecated with an error message pointing to the migration guide, and add 'runner_image' as the required replacement field.", "Release a CLI migration tool (e.g., 'platform-migrate --config pipeline.yml') that automatically renames the key in place and prints a summary of all files changed across a repository.", "Configure the platform's pipeline validator to emit a clear error message ('Error: build_image is removed in v3.0, use runner_image instead. See: docs.example.com/breaking-changes/v3') when the old key is detected."]
Teams receive immediate, actionable error messages pointing to the migration guide, and the automated CLI tool reduces manual YAML editing effort, enabling most teams to complete migration in under 10 minutes per repository.
Incrementing the major version number (e.g., v1.4.2 → v2.0.0) is the first and most universal signal to consumers that a breaking change has occurred. This allows package managers, dependency pinning, and automated tooling to protect consumers from accidental upgrades. Coupling semantic versioning with a clear policy statement in your documentation ensures the signal is understood.
A dedicated 'Breaking Changes' section in your CHANGELOG.md or release notes, separate from features and bug fixes, ensures consumers can quickly identify what will break and what action they must take. Each entry should include the affected component, the nature of the change, the reason for it, and a direct link to the migration guide. Structured entries reduce the time consumers spend triaging whether a change affects them.
A deprecation window of at least one release cycle (ideally 90 days for public APIs) gives consumers time to update their integrations before the breaking change takes effect. During this window, the old behavior should still work but emit deprecation warnings or response headers pointing to the migration documentation. This transforms a surprise breaking change into a managed, predictable transition.
Abstract descriptions of what changed are insufficient for developers under time pressure. Side-by-side code examples showing the exact old code pattern and its new equivalent dramatically reduce the cognitive load of migration. Examples should cover the most common use cases and be tested against the actual new version to ensure they are correct.
Documentation alone is insufficient if consumers are not actively reading release notes. Proactive notification through email, in-product banners, API response headers, and developer community channels (Slack, Discord, mailing lists) ensures that breaking changes reach consumers before they cause production incidents. Targeting notifications to consumers who are actively using the affected feature is more effective than broadcasting to all users.
Join thousands of teams creating outstanding documentation
Start Free Trial