Foundations — Contributing to open-source ML

The parent note throws around a lot of words as if you already know them: repo, fork, branch, PR, merge, maintainer, issue, test, dot product, norm, Big-O memory. This page builds every single one from zero, in an order where each idea rests on the one before it. Never used a terminal? Never seen $\Vert a\Vert$? Start at line one — you will not be left behind.

0. The picture the whole topic lives inside

Before any word, look at where code travels. Open-source means the code lives in a public place, you copy it, change your copy, then ask for your change to go back to the shared place.

1. Repository ("repo")

The picture: imagine a filing cabinet where you never throw a page away. Each time someone edits a file, the old page is kept and a new one is stacked on top. The repo is the whole cabinet, not just the top page.

Why the topic needs it: ML projects like PyTorch have thousands of files edited by thousands of people over years. Without a full history you could never answer "who broke this, and when?" — the question that makes safe collaboration possible.

Managing this history is a job in itself — see Version Control with Git.

2. Commit

The picture: each commit is a single photograph of the filing cabinet. Line up all the photos and you get a flip-book — the project's whole life as a movie.

Why the topic needs it: the parent note says "your commits are your resume." A commit is the atomic unit of contribution. When maintainers review you, they literally scroll through your photographs.

3. Branch

The picture (green track in Figure 1): think of the commit flip-book as a train track. A branch is a switch point where a side track splits off. You lay new commits on the side track; the main track is untouched. Later you can merge the tracks back together.

Why the topic needs it: the lifecycle line Create Branch exists so your half-finished experiment never touches the code everyone else depends on. Multiple contributors each work on their own branch at the same time without colliding.

4. Fork

The picture (orange box in Figure 1): a branch splits inside one repo; a fork copies the whole repo to a place you own. Branch = side track on the same railway; fork = building your own private railway that started as a photocopy of theirs.

Why the topic needs it: you have no permission to write into PyTorch's official repo (good — imagine if strangers could!). So you fork it, own the copy, and later ask for your changes to travel back. This is the "Fork Repo" step of the lifecycle.

5. Issue

The picture: a sticky-note board attached to the project. Anyone can post a note ("cosine_similarity crashes on 1D inputs"), and people reply underneath.

Why the topic needs it: the first lifecycle step is Find Issue → Claim It. Claiming means commenting "I'll take this" so two people don't fix the same thing. Issues are also where maintainers tag good-first-issue — the RAMP mnemonic's P — telling newcomers "start here."

6. Pull request ("PR")

The picture (red arrow in Figure 1): the PR is the arrow pointing from your fork's side-track back into the trusted blue original. It is a request, not a command — a human (or a check) must approve it.

Why the topic needs it: the entire parent page is really about making a good PR. The parent's quality formula $Q_{\text{PR}}=C_{\text{correct}}\times C_{\text{clear}}\times C_{\text{tested}}\times C_{\text{justified}}$ means the four boxes below must all be true. Multiplication is used because $0$ in any factor makes the whole product $0$ — a single failed dimension makes the PR unmergeable. We define each factor's underlying idea in the next sections.

Deeper craft of a persuasive PR lives in Code Review Best Practices and Technical Writing for ML.

7. Merge & Maintainer

The picture: two train tracks re-joining into one (right side of Figure 3). The maintainer is the switch operator who pulls the lever — but only after inspecting your carriage.

Why the topic needs it: Code Review → Revisions → Merge is the final stretch of the lifecycle. The reviewer is usually a maintainer; the Collaborative Machine Learning workflow is entirely about this human hand-off.

8. Test

The picture: a factory quality gate. A part rolls up, a machine measures it against a template, and either stamps ✅ or ✅ rejects it — no human judgement needed.

Why the topic needs it: the parent says "tests are non-negotiable." Look at its Example 2. The fixed cosine_similarity must be proven correct, so a test computes the expected answer by hand and compares. That is factor $C_{\text{tested}}$ in the PR formula. The discipline of writing these is Testing ML Systems.

9. Two maths tools the parent uses without defining them

The parent page silently assumes two pieces of maths. We earn them here.

9a. Dot product and norm (from Example 2's cosine similarity)

Example 2 writes cosine similarity as $\frac{a\cdot b}{\Vert a\Vert \Vert b\Vert }$. Two symbols there are undefined for a beginner: $a\cdot b$ and $\Vert a\Vert$.

The picture: slide the two arrows so their tails touch. The dot product is largest when they point the same way, zero when they are perpendicular, negative when they oppose. It measures "how much do these two point together."

Why the topic needs it: the whole bug in Example 2 is about shape — the code did .sum(dim=1) assuming a second dimension exists. To even understand what the correct value should be, and to write the test, you must know $a\cdot b$ and $\Vert a\Vert$. With $a=(1,2,3)$, $b=(4,5,6)$: $a\cdot b=1\cdot 4+2\cdot 5+3\cdot 6=32,\Vert a\Vert =\sqrt{14},\Vert b\Vert =\sqrt{77},$ $\cos =\frac{32}{\sqrt{14}\sqrt{77}}\approx 0.9746,$ exactly the number the parent's test checks.

9b. Big-O notation (from Example 3's memory maths)

Example 3 writes $\text{Memory}=O(L\cdot B\cdot H)$. The $O(\cdot )$ is undefined for a newcomer.

The picture: a straight ramp. $O(L)$ is a ramp whose height doubles when $L$ doubles. We don't care whether the ramp is painted red or blue (the constant) — only its slope shape.

Why the topic needs it: gradient checkpointing's whole selling point is a scaling claim: store checkpoints every $k$ layers and memory drops from $O(L\cdot B\cdot H)$ to $O(\frac{L}{k}\cdot B\cdot H)$, while compute rises from $O(L)$ to $O(2L)$. Big-O is the language that lets you argue "this tradeoff is worth it" — factor $C_{\text{justified}}$ — without pretending to predict exact GPU bytes.

Sanity check the ratio: with $k=4$ the model keeps $\frac{1}{4}$ of activations, so memory theory predicts $\approx 75\%$ savings. The parent's benchmark (23.4 GB → 8.1 GB) is a $65\%$ saving — close, the gap being the parameters and buffers that checkpointing does not shrink. Understanding why the real number falls short of the ideal is exactly the reasoning a strong PR shows. This links to Software Engineering for ML and ML Research Paper Implementation.

The prerequisite map

Read it top-to-bottom: history-tracking ideas (repo, commit, branch, fork) plus a ticket (issue), a checker (test), and the maths tools all converge into a pull request, which a maintainer reviews and merges — and that act is the contribution.

If you want the next steps after the foundations, see Building ML Portfolios.

Equipment checklist

Cover each answer before revealing. If you can answer all, you are ready for the parent page.