Versioning Public Datasets Without Breaking Consumers

Once a dataset is in a model's context, it is part of the surface. Renames and removals are breaking changes. A versioning policy that respects that is the difference between a dataset people trust and one they paste once and forget.

The three rules

1. Never silently rename a column. Add the new name, keep the old one for at least one year, then mark the old one deprecated in the header.
2. Never remove a row that consumers might be keying on. Mark it as deprecated: true and keep it. Filter on the consumer side.
3. Never reorder columns in a published snapshot. Append-only at the row level; append-only at the column level.

How to communicate a change

• Add a version field at the top of the dataset, bumped on any breaking change.
• Publish a CHANGELOG entry per version with the date and the exact diff.
• Mirror the same information in the blog post that announces the change.

What this costs you

A little duplication. A little extra disk. The benefit is that every consumer can pick a version and stay on it. That is the only deal that works for reference data.