Kaggle, GitHub and Python: the accounts, the Git workflow and the repository of a machine learning project

Why the whole project lives in a public repository

A project that only works on its author's laptop proves nothing; a public repository that anyone can rerun is the deliverable, and also a visible record of your work.

The three tools have three distinct jobs. Kaggle is the training ground: datasets already cleaned, a hosted machine, a leaderboard to measure yourself against others. GitHub is both the building site and the shop window: the code, its full history, the reviews and, at the end, the complete delivery. Python is the language everyone writes in, whatever their starting point. All three are free.

The final project is handed in as the address of a public repository, not as an attachment. That repository holds five things: a scope document written before any code, readable Python modules rather than one enormous notebook, batch scripts that rerun everything, the presentation (PDF and source), and a small web interface where a user enters a case and the model answers. A mid-course project on a UCI dataset uses the same structure and serves as the template.

A public repository is also a CV line that can be verified. GitHub's Octoverse report (October 2025) counted more than 180 million developers, 36 million new accounts in 2025 alone and about 630 million repositories, with Python at 2.6 million contributors. A recruiter who opens your repository typically spends a couple of minutes on it and looks for the same things a demanding reader would:

• a README that says in a few lines what the project does and how to run it;
• a steady history whose commit messages explain why, not just "fix";
• a handful of tests and one command that runs them;
• honest, quantified results with the evaluation method stated;
• no secrets, no personal data, no huge binary files.

Back to contents.

Kaggle: competitions, metrics and the two leaderboards

A Kaggle competition gives you training data with the answers, test data without them, a metric, and a ranking; the ranking that counts is the one you cannot see until the end.

Kaggle was founded in 2010 as a marketplace for prediction contests and bought by Google in March 2017, which added hosted notebooks with GPUs. Its counter showed more than 34 million members when read on 11 October 2026. Every competition page has the same parts: an overview (problem, metric, submission format), the data (train.csv with the target, test.csv without it, and a sample submission), public notebooks, the leaderboard and the rules, including a daily submission limit.

Titanic: classification, measured by accuracy

The Titanic competition asks which passengers survived: 891 labelled passengers to learn from, 418 to predict, and a two-column CSV (PassengerId,Survived) to submit. The metric is accuracy, the share of correct answers. The baseline file supplied by Kaggle, which simply predicts that every woman survives, already scores 0.766; an honest model lands around 0.78 to 0.80.

House Prices: regression, measured on the logarithm

House Prices uses Dean De Cock's Ames, Iowa dataset (Journal of Statistics Education, 2011), built to replace the old Boston housing data: 1,460 houses for training, 1,459 to predict, 79 variables, and missing values that carry meaning (no garage, no pool). The metric is the root mean squared error between logarithms of predicted and observed prices, so it measures a relative error.

On these three houses the metric is $\sqrt{(0.095^2 + 0.095^2 + 0.105^2)/3} \approx 0.099$. For orientation, the deck gives rough levels on the real competition: predicting the mean scores about 0.40, a clean linear regression about 0.15, a well-tuned tree ensemble about 0.12. That ladder, a naive model, a better one, then a heavy one, compared on the same unseen data, is the thread of the whole course.

Public and private leaderboard

The test set is split in two. The public part is scored after every submission; the private part is revealed only at the deadline. Tuning endlessly against the public score is overfitting to a few hundred rows, and the private ranking punishes it. The only defence is an internal validation built from the training data. On the Titanic, perfect scores of 1.000 exist because the passenger list is public: that is a data leakage, not a model, and the course teaches how to recognise one from session 2.

Kaggle notebooks are hosted Jupyter sessions with the data already mounted and a weekly GPU quota; "Copy & Edit" keeps a link to the original, the fair way to build on others' work. Kaggle Learn adds four short free courses, about sixteen hours in all.

Back to contents.

Git is not GitHub: the tool, the site and ten words

Git is a program on your computer that records every state of a project; GitHub is a website that hosts those records and adds what a team needs to work together.

Linus Torvalds wrote Git in April 2005 for the Linux kernel, after the tool the kernel used lost its free licence. Git runs locally, offline, without an account: it records who changed what, when, and why. GitHub, launched in 2008 and bought by Microsoft in 2018, hosts Git repositories and adds pull requests, issues, reviews, web pages and automated actions. GitLab, Codeberg and Bitbucket do similar jobs; the course uses GitHub.

The problem Git solves is familiar to anyone who has shared a folder: model_v2_final.ipynb, model_v2_final_REAL.ipynb, and nobody knows which version works or who changed the metric. Under Git there is one file and a list of dated, signed states, each with a one-line message saying what changed and why. Any state can be reopened, compared with the previous one, or cleanly undone.

Picture the commit graph with time running left to right. The principal line, main, carries the initialisation, then the scope document, then the baseline. A branch leaves to try a heavier model and comes back through a merge once a teammate has reviewed the pull request. A tag can mark the delivered commit. The team rule that follows is simple: `main` must always work; anything uncertain happens on a branch.

Choose the GitHub username with care, since it will sit in every project address and on your CV, and turn on two-factor authentication with the recovery codes stored somewhere safe.

Back to contents.

The daily cycle, one branch per task, and conflicts

Each working day follows the same four moves, pull, edit, commit, push, and each task lives on its own branch until a teammate has reviewed it.

One team member creates the repository, public from day one, with a short lowercase hyphenated name, a README, the Python .gitignore template and a licence, then invites the others as collaborators. The licence is the step people forget: without one, a public repository is "all rights reserved", readable but not reusable. MIT is the simplest choice for a student project.

The four daily moves

1. Pull. Fetch what teammates have pushed before touching anything; most beginner trouble starts with a forgotten pull.
2. Edit and check. Change one thing, then run git status to see exactly what has moved.
3. Commit. Stage only the files that belong together and write a message that says why, not just what.
4. Push. Put the commit online so the others can build on it.

git pull                      # start from the team's latest state
git status                    # what has changed here
git switch -c xgboost-model   # one branch per task
git add src/project/models.py
git commit -m "Add XGBoost with early stopping"
git push -u origin xgboost-model   # then open the pull request

VS Code's Source Control panel, GitHub Desktop and Codespaces make the same moves with buttons, but at least one person per team should be at ease in the terminal, where batch scripts run.

With three people, every task gets its own branch. Once pushed, the branch becomes a pull request with a short description: what, why, how to check. A teammate comments line by line, approves, and the branch is merged and deleted. This is where a team learns the most, because it is where people agree on what good code and a good result look like. A history in which one person pushed everything describes a one-person project, whatever the list of authors.

Back to contents.

Notebooks, secrets and large files: what stays out of the repository

A repository should contain what is needed to rebuild the project and nothing that is secret, personal, huge or regenerated automatically.

A notebook is a JSON file that stores its outputs next to the code, so two runs of identical code give two different files and Git's diff becomes unreadable. Clear the outputs before committing, let nbstripout do it automatically, or, best, move the code that matters into modules under src/ and keep the notebook for exploration.

• Secrets: API keys, passwords, .env files, the Kaggle token. A secret pushed once stays in the history even if deleted in the next commit, and automated bots harvest such leaks within minutes.
• Large files: GitHub warns above 50 MB and refuses files above 100 MB. Raw data is described in data/README.md and downloaded by a script.
• Personal data: names, e-mail addresses, customer identifiers, never in a public repository, even as a quick test.
• Anything regenerable: virtual environments, caches, trained models, notebook outputs.

The .gitignore file lists the patterns Git must ignore. GitHub's Python template already covers virtual environments and caches; a data project adds lines for the raw data folder, CSV files, serialised models, logs and credential files.

The Kaggle command-line client (pip install kaggle) is the clearest example of why this matters. It lets a script download the competition data and submit a file with a message, much like a commit, which is exactly what a project's batch scripts will need. Logging in stores an access token in ~/.kaggle/. That token is a password: it never goes into a repository, a shared notebook or an e-mail, and if it leaks you revoke it and log in again.

Back to contents.

The layout of a reproducible project repository

A good repository is organised so that a stranger understands the project in thirty seconds, can run it in two minutes, and finds each deliverable where its name says it is.

credit-risk-project/
  README.md          # what, for whom, how to run, results
  docs/scope.md      # the scope document
  docs/journal.md    # dated decisions
  data/README.md     # where the data comes from
  notebooks/         # exploration, outputs cleared
  src/project/       # data, features, models, evaluate
  batch/             # prepare, train, predict, evaluate
  app/               # the web interface
  slides/  tests/  requirements.txt  config.yaml  LICENSE

The README is often read instead of everything else. Four blocks are enough: one sentence on what the model predicts and for whom; the three or so commands to run it, which must work as written on a clean machine; a results table comparing the naive, better and heavy models on data never seen in training; the authors, the licence and links to the slides and the live interface.

The scope document carries the framing from the first session into the repository: the decision the model serves, the target defined in one unambiguous sentence, the metric that measures that decision, the guard-rails (forbidden variables, protected groups, leaks), the data and its provenance, and the plan. It is one versioned Markdown page, changed by pull request whenever the team changes its mind, so its history shows how the understanding of the problem matured. The framing itself is developed in the note on least squares and problem framing.

Batch scripts are the core of reproducibility. A notebook run out of order can show results its code no longer produces; a script runs top to bottom, the same way, for anyone, including a machine at night. Four scripts (prepare, train, predict, evaluate) and one command that chains them, such as make all or a run.sh. Every setting (data path, random seed, decision threshold, hyperparameters) lives in config.yaml, so changing an experiment never means editing code. Session 4 builds that chain on a credit-scoring case; see the decision threshold and reproducible ML.

Issues are the team's task board: one numbered issue per task, with an owner and a milestone, closed automatically by a commit message such as Fixes #17.

The web interface deploys from the repository at no cost: Streamlit Community Cloud by default, Hugging Face Spaces with Gradio, or GitHub Pages for static pages. The minimum is a form that takes a case and returns a prediction with its confidence.

A worked example of this structure is the credit default scoring project, and ideas for subjects on open data are collected in open-data machine learning projects.

Back to contents.

Python: the libraries, your starting point, and how to install it

Five libraries cover the whole course, and whether you have never coded or are already comfortable, there is a short path to being ready for the first project milestone.

Guido van Rossum released Python in February 1991. It became the common language of data because every library that matters is written for it and a beginner can read it. The course needs five: pandas for tables, NumPy for vectors and matrices, scikit-learn for models, validation and pipelines, Matplotlib (with Seaborn on top) for figures, and XGBoost for the heavy tabular model. The code of every model in the course is gathered in Python code for machine learning models.

Three starting points

1. Never coded. Start with short browser-based Python lessons on finance cases (variables, loops, functions, then pandas), then Kaggle's Python course; plan about ten hours before attempting the Titanic.
2. Some Python. Go straight to Kaggle's Pandas course, then the official Titanic tutorial: reading a CSV, cleaning it and submitting.
3. Comfortable. Take Intermediate Machine Learning (pipelines, cross-validation, XGBoost, leakage), build the heavy model early, and help the rest of the team.

# one environment per project, so versions never mix
conda create -n project python=3.12
conda activate project
pip install -r requirements.txt
python -c "import sklearn, pandas, xgboost"   # no error means ready

If the last line runs without error, everything is in place; versions frozen in requirements.txt let another machine rebuild the same environment.

Back to contents.

Key takeaways

1. Kaggle is for training, GitHub for delivering, Python for writing; all three are free and all three show on a CV.
2. A Kaggle score is only meaningful against an internal validation: the public leaderboard can be overfitted, and a perfect score usually signals a leak.
3. Git records states of a project; GitHub hosts them and adds pull requests, reviews and issues. Keep main working and put anything uncertain on a branch.
4. The daily cycle is pull, edit, commit with a message that says why, push; one branch per task and one reviewed pull request per branch.
5. Secrets, personal data, large files and regenerable outputs never enter a repository; a pushed token stays in the history.
6. A reproducible project has a README, a scope document, modules in src/, settings in a configuration file and batch scripts that rebuild everything with one command on a clean machine.

Glossary

repository

A project folder together with its complete version history, hosted locally and usually on GitHub.

branch

A parallel line of work; main is the principal branch and must always work.

pull request

On GitHub, a request to merge a branch, which a teammate reviews before it is merged.

merge conflict

Two branches changed the same lines; Git writes both versions and a person chooses.

public and private leaderboard

The two rankings of a Kaggle competition: one scored on part of the test set during the contest, the other revealed at the deadline.

data leakage

Information about the answer that reaches the model during training or prediction, inflating the score without real skill.

scope document

One Markdown page stating the decision served, the target, the metric, the guard-rails, the data and the plan.

batch script

A script that runs a step from start to finish without human intervention, such as prepare, train, predict or evaluate.

virtual environment

An isolated set of Python packages for one project, so that library versions do not clash between projects.

baseline

The simplest reasonable model, such as predicting the mean, against which every other model is compared.

The other notes of the course

One public summary per deck, in the order of the course.

Previous: AI winters, jobs and methodNext: Project framing and least squares

1. IntroductionAI winters, jobs and method
2. ToolsKaggle, GitHub, Python: the tools
3. Session 1Project framing and least squares
4. Session 2Maximum likelihood and logistic regression
5. Session 3Gradient descent, ridge and lasso
6. Session 4Decision threshold and reproducible ML
7. HomeworkA defensible baseline model
8. Session 5Kernels, SVM and decision trees
9. Session 6Forests, boosting, honest comparison
10. Session 7SHAP, fairness, PCA and clustering
11. HomeworkA documented champion model
12. Session 8Neural networks, drift, conformal prediction
13. HomeworkA delivered machine learning project
14. Session 9Defending a machine learning project
15. ReferenceCredit default scoring project
16. ReferenceAsset returns: XGBoost and sentiment
17. ReferencePython code for every ML model
18. ReferenceDeep learning essentials
19. ReferenceOpen data ML projects by sector
20. ReferenceData and AI engineer handbook
21. ReferenceData engineering, SRE and cloud
22. ReferencePanorama of machine learning models

All the notes, as a reading list

Attention and transformers, step by step

About these notes

Written by the lecturer from the slides of the deck, as a public summary: the key ideas, the formulas and one worked example. The exercises, their solutions, the tests and the grading stay in the deck, for the students of the course.

Revision: 16 October 2026.