How Should a Change Log Describe a Breaking Change?
From the earlier reference collection. Read the current software blog.
A useful breaking-change note names the old and new behavior, tells users what migration requires, and pins the change to a release or effective date.
Identify who and what changes
Start with the affected interface or behavior in terms a user can recognize: a command-line flag, file field, API response, configuration key, or default. State what used to happen and what happens after the change. “Improved parsing” does not tell a client whether its workflow will break. A concise note might say that the tool no longer treats a blank timestamp as midnight and now reports the row as invalid.
Clarify the scope. Does the change affect every user, only a particular endpoint, or only projects that rely on an undocumented behavior? If compatibility differs across versions, make that boundary explicit. Do not describe a change as breaking merely because internal code was reorganized; focus on observable effects that require a user or downstream maintainer to act.
Provide a migration path
Give the concrete step that restores or adapts the workflow. That could mean renaming a configuration key, converting a field, updating a call signature, or handling a new error case. If several actions are needed, put them in sequence and include a short before-and-after example. Identify whether a migration script exists only if it is actually available, and state what it changes before asking users to run it.
Explain any data or behavior risk. A file-format change may require rewriting stored records; a stricter parser may reject inputs previously accepted. Tell users how to check whether they are affected and how to validate the result after migration. If a temporary compatibility option exists, document its limits and removal plan only when those are established. Avoid vague advice like “update your integration” without naming the work involved.
Anchor the notice in time
Name the release where the behavior changes and, when relevant, the date it takes effect. If a staged rollout means versions behave differently over time, explain the sequence. Link to detailed migration instructions, issue discussions, or the relevant reference entry so readers can find more than the summary. The change log itself should remain useful even if a linked discussion moves or grows lengthy.
A practical entry could say: “Version 2.4 removes the --local-time option. Replace it with --timezone Europe/Paris; existing scripts using the old flag will exit with an unknown-option error. Update scheduled jobs before upgrading, then run the command with --help to confirm the new flag is available.” Include only details that match the actual release. This combination of impact, action, and timing lets operators schedule upgrades and lets maintainers distinguish a compatibility change from ordinary feature work.