How to Showcase Machine Learning Projects on GitHub Properly

churn-prediction/
├── README.md
├── requirements.txt
├── .gitignore
├── config.yaml
├── data/
│   ├── README.md          # where to download data, licence
│   └── sample.csv         # small sample only
├── notebooks/
│   ├── 01_eda.ipynb
│   └── 02_model_comparison.ipynb
├── src/
│   ├── data.py
│   ├── features.py
│   ├── train.py
│   └── evaluate.py
├── models/                # ignored by git, or a small final model
├── reports/
│   └── figures/
└── tests/
    └── test_features.py

# Python
__pycache__/
*.pyc
.venv/

# Notebooks
.ipynb_checkpoints/

# Data and models (keep repo small; document how to get them)
data/*
!data/README.md
!data/sample.csv
models/*
!models/.gitkeep

# Secrets
.env

# Customer Churn Prediction

Predicts which telecom customers may leave next month so a
retention team can contact them first.

## Data
Public telecom churn dataset (link), ~7k rows, target: `churn`.

## Approach
1. EDA and cleaning (notebooks/01_eda.ipynb)
2. Baseline: logistic regression
3. Gradient boosting with tuned threshold

## Results (test set)
| Model               | Recall | Precision | ROC-AUC |
|---------------------|--------|-----------|---------|
| Baseline (logistic) | ...    | ...       | ...     |
| Gradient boosting   | ...    | ...       | ...     |

## Run it
```
pip install -r requirements.txt
python src/train.py --config config.yaml
```

# src/evaluate.py - save a figure for the README
import matplotlib.pyplot as plt
from sklearn.metrics import ConfusionMatrixDisplay

def save_confusion_matrix(model, X_test, y_test, path="reports/figures/confusion.png"):
    disp = ConfusionMatrixDisplay.from_estimator(model, X_test, y_test, cmap="Blues")
    disp.ax_.set_title("Churn model - test set")
    plt.tight_layout()
    plt.savefig(path, dpi=150)
    plt.close()

# Then reference it in README.md:
# ![Confusion matrix](reports/figures/confusion.png)

# src/train.py  - run: python src/train.py --config config.yaml
import argparse, yaml, joblib
import pandas as pd
from sklearn.model_selection import train_test_split
from sklearn.ensemble import GradientBoostingClassifier

parser = argparse.ArgumentParser()
parser.add_argument("--config", default="config.yaml")
cfg = yaml.safe_load(open(parser.parse_args().config))

df = pd.read_csv(cfg["data_path"])
X, y = df.drop(columns=[cfg["target"]]), df[cfg["target"]]
X_tr, X_te, y_tr, y_te = train_test_split(
    X, y, test_size=cfg["test_size"], stratify=y, random_state=cfg["seed"])

model = GradientBoostingClassifier(random_state=cfg["seed"], **cfg["model_params"])
model.fit(X_tr, y_tr)
joblib.dump(model, cfg["model_path"])
print("test accuracy:", round(model.score(X_te, y_te), 3))

# config.yaml - all settings in one place
data_path: data/sample.csv
target: churn
test_size: 0.2
seed: 42
model_path: models/churn_model.joblib
model_params:
  n_estimators: 200
  max_depth: 3
  learning_rate: 0.05

# Note: the sample CSV must contain only numeric features
# (encode categories in src/features.py before training).

# Model Card: Churn Prediction v1

## Intended use
Prioritise customers for retention calls. Not for pricing decisions.

## Data
Public dataset, time period, known gaps.

## Performance
Metrics on held-out test set, plus results by customer segment.

## Limitations
- Trained on one market's data
- May not reflect new plans or offers

## Ethical considerations
No sensitive personal attributes used as features.
Predictions should support, not replace, human decisions.

GitHub profile checklist

[ ] Professional photo or simple avatar, real name
[ ] Bio: "Aspiring ML engineer | Python, scikit-learn, PyTorch"
[ ] Profile README with 3-4 lines and links
[ ] Pin 3-4 best repos (not forks of tutorials)
[ ] Each pinned repo has a clear description and topics
[ ] Remove or archive unfinished experiments
[ ] Regular, meaningful commits (not one big upload)

Before sharing an ML repo:

[ ] README explains problem, data, approach, results
[ ] Baseline included in results
[ ] Code runs from a fresh clone using README steps
[ ] requirements.txt pinned, seeds fixed
[ ] Notebooks cleaned: no huge outputs or errors
[ ] No secrets, API keys or private data
[ ] Figures saved and shown in README
[ ] Limitations stated honestly