Machine Learning Best Practices For Your Company

Early-stage ML teams often lose more velocity to messy repos, unversioned datasets, and mystery notebooks than to hard modeling problems. I originally put this checklist together as an onboarding doc for new data scientists, ML engineers, and analysts joining the team so everyone shipped code the same way.

Git and GitHub/GitLab Essentials

• Get comfortable with Git: If you’re new to version control, Udacity’s free “Version Control with Git” course takes a weekend.
• Configure your identity: Set user.name and user.email in your local Git config and add an SSH key to your GitHub/GitLab account so every commit traces back to a real author.
• Everything lives in a repo: Never leave training scripts or SQL queries stranded on a single EC2 box or laptop. Make sure you have access to the org’s GitHub/GitLab groups on day one.
• Protect main: Never push directly to main or master. Work on short-lived feature branches, tag releases, and merge through pull requests.
• Treat PR reviews seriously: Every change goes through a PR. Even if you’re a solo engineer on a repo, open a PR and read your own diff from top to bottom before merging; you’ll catch leftover debug prints and broken imports immediately.
• Pick a workflow tool that fits how you work: GitHub Desktop works well if you prefer a visual diff viewer, and the official gh CLI makes opening and checking out PRs quick from the terminal.

.gitignore Hygiene

• Keep build noise and weights out of Git: Virtual environments, __pycache__, dataset CSVs, and .pt/.h5 checkpoints do not belong in Git history.
• Start from a template: Generate a language- and IDE-specific .gitignore on commit #1 using gitignore.io.

Commit Messages That Help Future You

• Explain the what and the why: Six months from now, git log shouldn’t read fix, wip, try again. Chris Beams’ guide to Git commit messages and freeCodeCamp’s walkthrough are great references.

Handling Secrets and API Keys

• Never commit credentials: API keys, database URLs, and cloud tokens belong in a secret manager or a local .env file that is explicitly listed in .gitignore.
• If a secret leaks into Git: git rm is not enough, because the key is still sitting in the commit history. Rotate the credential immediately, let your lead know, and follow GitHub’s guide to purging sensitive data from history.

README.md

• Write the README you’d want to read at 2 a.m.: Every repo needs a README.md that explains what the service or model does, how to set up the environment, how to run tests, and how to deploy. jehna/readme-best-practices is a great starting skeleton.

Git Hooks

• Catch lint and formatting issues before push: Wire up pre-commit hooks (githooks.com / pre-commit) to run formatters, linters, and secret scanners automatically on git commit.

Data & Model Versioning

• Use DVC for large artifacts: Git is not built for multi-gigabyte datasets and model weights. Pair Git with DVC (Data Version Control) so large files live in S3/GCS while lightweight .dvc pointer files stay versioned right alongside your training code.

Machine Learning Engineering Discipline

• Automate model reports in CI with CML: Continuous Machine Learning (CML) lets your GitHub Actions or GitLab CI pipelines post training metrics and confusion matrices straight into pull-request comments.
• Read Google’s Rules of ML: Before reaching for a complex architecture, read Martin Zinkevich’s Rules of Machine Learning, especially Rule #1 (Don’t be afraid to launch a product without machine learning) and Rule #4 (Keep the first model simple and get the infrastructure right).

Jupyter Notebook Standards

• Notebooks are for exploration, modules are for reuse: Keep JupyterLab notebooks clean, restart-and-run-all reproducible, and scoped to exploratory analysis or visualization.
• Extract shared logic and test it: The moment a preprocessing function or model class is used in two places, move it into a proper Python package and cover it with unit tests (see this practical guide on TDD for ML).

Experiment Tracking

• Log every run in MLflow: Don’t track hyperparameters in a spreadsheet or a Slack thread. Wire MLflow into your training loop from the start (tutorials here) so every run records its exact Git SHA, hyperparameters, metrics, and model artifact.

Modernizing MLOps

• Use AI coding tools where they save boilerplate: Lean on LLMs and GitHub Copilot to draft boilerplate tests, docstrings, and data-loader scaffolding, then review the generated code with the same rigor you’d apply to a human PR.
• Bring models into CI/CD: Model training, evaluation gates, and container builds belong in automated pipelines, not manual SSH sessions. For the broader philosophy, see “MLOps: Machine Learning as an Engineering Discipline”.