In the previous article, we focused on code, how to take a repository and make it usable without relying on internal context.

Author: Hirad Emamialagha

Machine learning adds another layer on top of that. Code is still important. You need it for training, for evaluation, for extending the work later. But on its own, it is usually not enough.

For a project centered on a specific result, a repository with clean code but no model or data can feel like an empty shell. This is different from a general-purpose library where the code is the product. In a model-driven release, the code is there to support the model, not the other way around. Without the weights, you are missing the thing that actually produces the results you're claiming.

At the same time, releasing only a model without context does not help much either. A checkpoint file without a clear way to load it, evaluate it, or understand how it was trained ends up being difficult to use.

So the problem is not choosing between code, models, or data. It is making sure they stay connected.

A trained system is only really useful when the code, model, and data stay connected.

What Actually Needs to Be Released

A typical machine learning project involves several components.

Training code, evaluation scripts, inference logic, model checkpoints, and datasets. Experiments integrate all components.

When moving toward open source, the question shifts. Instead of asking what exists, it becomes:

What does someone need to run, understand, and modify?

Usually, this includes:

• The code for training and evaluation

• A model that can be loaded and tested

• Data access, either direct or reproducible

• A minimal path from input to output

Not everything has to be released, but what you share depends on your goal. If the intent is just to let people run the model, a checkpoint on Hugging Face might be enough. But if the goal is for others to verify or extend the work, then missing scripts or data recipes become blockers. You have to decide where the boundary is based on how you want the project to be used.

The gaps in a project only become visible when someone tries to use it without context.

Keeping the Pipeline Intact

Machine learning pipelines are rarely simple.

They involve data collection, preprocessing, feature preparation, training, validation, testing, and inference, sometimes under different assumptions than training.

It's easy to overlook parts when preparing for release.

Some steps might reside internally in notebooks, scripts, or manual processes. When exposing the system, gaps appear.

A dataset might exist, but its preprocessing is unclear. A model might work, but the training configuration is missing. Evaluation scripts might rely on a directory structure that no longer exists.

You do not need perfection, but the pipeline should be understandable end to end.

If the pipeline is unclear, the model is hard to trust.

Models Need Context

A trained model is often the most visible artifact but also the easiest to misinterpret.

Without context, answering simple questions is difficult: what data was used, what the expected input looks like, what outputs to expect, and where it performs well or poorly.

This highlights the importance of documentation around the model.

In practice, most models are shared through platforms like Hugging Face. Not because it is the only option, but because it provides a consistent place to store the model, version it, and describe its usage.

A model card is usually the first thing someone sees. It does not need be long but should answer basic questions without forcing the reader to search the repository.

What the model expects as input, what it produces as output, what it was trained on, expected performance, and common failure modes.

If these answers are missing, people may guess incorrectly.

Another lesson from publishing models: versioning becomes quickly essential. Models change, and without clear versions, it is hard to know which model produced which result.

You do not need a complex setup, but you must identify which model produced each result.

The model card is usually the first place where expectations are set.

Data Is Often the Limiting Factor

Data is usually where things get complicated.

Sometimes it can be shared directly. Sometimes it cannot be shared because of licensing or size, but often it comes down to privacy. You have to balance the need for a reproducible pipeline with the responsibility of keeping sensitive data secure. In those cases, the focus shifts to documenting the transformation logic rather than the raw inputs.

Both cases show up often.

When the dataset can be released, it still needs structure. Clear splits, consistent format, some explanation of what is included and what is not.

When it cannot be released, the next best option is to provide a way to recreate it.

That might mean scripts that download raw data from public sources and apply the same transformations used internally. It might not produce an identical dataset, but it should be close enough to reproduce the behavior of the system.

This tends to surface hidden steps. Small preprocessing decisions that were never written down suddenly matter.

Data decisions tend to surface only when you try to share them.

Data Cards and Dataset Context

Datasets face a similar issue.

Even when shareable, they often do not explain themselves. File structure alone reveals little. You must know the data's origin, processing steps, and assumptions made.

Platforms like Hugging Face provide structure through data cards.

Data cards serve the same purpose as model cards but for datasets.

They detail data origin, collection methods, preprocessing, splits, biases, and limitations.

This is crucial when datasets aren't directly released.

In such cases, data cards often provide the only complete picture. Scripts may recreate datasets, but the rationale must be documented.

Without this context, reproducing datasets is possible, but understanding them is difficult.

The real goal here is traceability. It is less about getting the exact same numbers and more about being able to map a model back to the specific code, data, and config that created it.

Examples Make the Difference

Even with code, models, and data in place, people still need an entry point.

This is where examples come in.

A simple script that loads the model, runs inference on a sample input, and produces an output. That is usually enough to get someone started.

Without that, the first interaction is often unclear. Where to begin, what to run, what “correct” looks like.

Examples do not need to be polished. They just need to work.

A working example is often the difference between curiosity and actual usage.

Reproducibility Shows Up Differently Here

In an open source setting, exact reproducibility is usually the exception. You have no control over the drivers or hardware someone else is using, so the best you can do is provide enough context that they can get close.

Small differences in environment, randomness, or data ordering can change results. Even with the same code and configuration.

But that does not make reproducibility irrelevant.

It changes what you aim for.

Instead of exact replication, the goal is to make the process understandable and close enough to follow. Training scripts, configuration files, evaluation logic. Enough detail so someone else can see how results were produced.

In practice, this is often where projects either become useful or remain as references.

Reproducibility is less about exact results and more about understanding the process.

Evaluation Needs to Be Visible

Evaluation is often sought but scattered.

Some results appear in papers, others in logs.

Reproducing the numbers is not always straightforward.

At minimum, two questions require clear answers:

How well does the model perform, and how fast does it run on specific hardware? Performance metrics don't mean much in a vacuum, so you have to mention if you were testing on a high end GPU or a standard CPU.

Performance usually comes from evaluation scripts that run the model on a dataset split and compute metrics like accuracy, F1, or BLEU. The key is that this process is visible and runnable.

Speed is often ignored but matters: inference time, memory use, throughput.

A model might be accurate, but if it is too slow for its intended use case, it probably won't see much adoption outside of pure research.

You don't need full benchmarks; a simple script running inference on a small batch and reporting latency helps.

For example:

• Load model

• Run on N samples

• Report average latency

This gives a rough idea.

With both metrics, people can make informed choices, compare models, understand trade-offs, and see if a model fits their needs.

Without this, they're left guessing.

If evaluation is not visible, results are hard to interpret.

Versioning Across Code, Models, and Data

Versioning changes when models are involved.

Usually, code versioning suffices by tagging stable releases.

In machine learning, this isn't enough.

A model checkpoint depends on code, data, config, and training setup; any change may affects results.

This makes versioning complex.

You have a model file and a changing repo with no clear link, making it unclear which version made which result.

A practical method treats each model as output of a specific run, not just an artifact.

That run must be identifiable.

In practice, keep these consistent:

• Code version used for training

• Dataset version or snapshot

• Configuration used for the run

• Evaluation setup producing reported metrics

You don't need a complex system; a simple, consistent approach works.

One effective pattern:

• Tag a code release when training starts

• Store the run's configuration with the model

• Version the dataset or reference a fixed snapshot

• Publish the model with a matching version or tag

• Link everything in the model card

This anchors the model to a concrete system state.

Keep training, evaluation, and inference code aligned with the same version. Original evaluations should be reproducible even if scripts change.

It needn't be perfect, but you should answer key questions without digging through commits:

Which code produced this model? What data was used? How were metrics generated?

If clear, the system stays coherent. If not, things drift and guessing begins.

This problem appears later when comparing models or explaining results without clear traceability.

A model is not just a file, it is a snapshot of a full system.

A Quick Sanity Check

A simple way to test the setup:

Take the released model. Follow the instructions. Try to run inference on a small example.

If that works without guessing, most of the pieces are in place.

If it does not, the missing parts usually become obvious. A configuration file is not clear. An input format is not documented. A dependency is not installed.

If the first run requires guessing, something is missing.

Final Thoughts

Releasing machine learning work is mostly about keeping the pieces connected.

Code, models, data, and examples all depend on each other. When one is missing or unclear, the whole system becomes harder to use.

You do not need to expose everything. But the path from input to output should exist and be understandable.

Machine learning projects become usable when their parts stop drifting apart.

What Comes Next

The next article moves into research itself.

Papers tend to follow a different workflow, but many of the same problems show up again. Versioning, reproducibility, and structure. Just in a different form.