Visual walkthrough — Contributing to open-source ML

Prerequisites you may want open in another tab: Code Review Best Practices, Testing ML Systems, Version Control with Git.

---

Step 1 — What is a "PR" and what are we even scoring?

WHAT. A Pull Request (PR) is a proposal: "Here is a bundle of code changes — please add them to the project." A human maintainer reads it and answers a single yes/no question: merge it, or not?

WHY we need a score. If the answer is just yes/no, we want to understand what pushes it toward yes. A score is just a number we attach to the PR that predicts "will this be merged?" — higher number, more likely to merge. We will call that number $Q_{\text{PR}}$, read aloud as "the quality of the pull request". The subscript "PR" is just a label reminding us what the $Q$ refers to; it does no maths.

PICTURE. Think of the PR as a package arriving at a gate. The gatekeeper (maintainer) inspects it and either opens the gate (merge) or turns it away (reject).

---

Step 2 — Break the package into four honest questions

WHAT. A maintainer's decision is not one gut feeling; it is really four separate checks. Each check is a plain question with a yes/no answer:

• Does it actually work? — call this check $C_{\text{correct}}$.
• Can a stranger read it and understand what it does? — call this $C_{\text{clear}}$.
• Will it still work next month when someone else edits nearby code? — call this $C_{\text{tested}}$.
• Was this the right problem to solve, and this the right way? — call this $C_{\text{justified}}$.

The letter $C$ just stands for Check. The subscript names which check.

WHY these four and not others. These map exactly onto the four things a reviewer physically does when reading a PR (see Code Review Best Practices): run it, read it, look for tests, and ask "why". Nothing a reviewer cares about falls outside these four — so they are complete. And they don't overlap — passing "it runs" tells you nothing about "is it readable" — so they are independent. Complete + independent is exactly what you want from a checklist.

PICTURE. The one package now passes through four gates in a row, each stamping a $1$ (pass) or $0$ (fail).

---

Step 3 — Why combine them with multiplication, not addition?

Here is the heart of the whole formula. We have four numbers, each $0$ or $1$. We must combine them into one score. There are two natural candidates.

Candidate A — add them: $Q=C_{\text{correct}}+C_{\text{clear}}+C_{\text{tested}}+C_{\text{justified}}$. Candidate B — multiply them: $Q=C_{\text{correct}}\times C_{\text{clear}}\times C_{\text{tested}}\times C_{\text{justified}}$.

WHY multiplication wins. Ask: what should happen if the PR fails exactly one check? Say the code is correct, clear, and justified — but has no tests, so $C_{\text{tested}}=0$.

• Addition gives $1+1+0+1=3$. That is a high score — as if three-out-of-four is "pretty good". But an untested change to a machine-learning library will not be merged. Addition rewards partial credit, and partial credit is a lie here.
• Multiplication gives $1\times 1\times 0\times 1=0$. Any single failure zeroes the whole thing. That is exactly the real rule: one fatal flaw sinks the PR no matter how good the rest is.

This "any zero kills everything" behaviour is the defining superpower of multiplication with $0/1$ inputs — it acts as a logical AND. The reason we choose this tool over addition is precisely that a mergeable PR must pass all checks simultaneously, never "mostly".

PICTURE. Below, the same four gates, but we watch what a single $0$ does to the running product versus the running sum.

---

Step 4 — Why each factor is exactly $0$ or $1$ (and nothing between)

WHAT. We declared each $C$ to be binary in Step 2. Now let's justify why we don't allow, say, $C_{\text{clear}}=0.7$ ("kind of readable").

WHY binary. The moment you allow fractions, the "AND" meaning breaks. Watch:

• If $C_{\text{tested}}=0.5$ (half-tested) and everything else is $1$, then $Q_{\text{PR}}=1\cdot 1\cdot 0.5\cdot 1=0.5$. That reads as "half-mergeable" — but there is no such thing. It either merges or it doesn't.
• Binary values keep $Q_{\text{PR}}$ itself binary: a product of $0$s and $1$s is always $0$ or $1$. So the output stays a clean verdict.

The reviewer's job during Revisions (from the parent's lifecycle) is precisely to flip any $0$ up to a $1$. Each round of code review targets one failing factor and fixes it — turning $0\to 1$ — until the product finally reaches $1$.

PICTURE. A truth-table grid: every combination of the four switches, and the single lit cell where the product equals $1$.

---

Step 5 — The maximum value is 1: why it can't be bigger

WHAT. We claim $Q_{\text{PR}}$ can never exceed $1$; its best possible value is exactly $1$.

WHY. Multiply the largest allowed value of each factor: $1\times 1\times 1\times 1=1$. Since no factor can be larger than $1$, no product can be larger than $1$. So $Q_{\text{PR}}\in \{0,1\}$ — the score lives on two values only, and $1$ is the ceiling.

This is why "a perfect PR scores $1$" is meaningful: $1$ is not an arbitrary grade, it is the mathematical maximum of the expression. Reaching it means every gate stamped a pass.

PICTURE. A number line with only two dots — $0$ and $1$ — and every one of the 16 combinations landing on one of them.

---

Step 6 — The degenerate cases (never leave a gap)

Let's deliberately walk the corners so no scenario surprises you.

Case A — the empty PR (no changes at all). There is nothing to be correct, clear, tested, or justified. Convention: an empty PR has $C_{\text{correct}}=0$ (it fixes nothing), so $Q_{\text{PR}}=0$. Good — an empty package should not merge.

Case B — all four fail. $0\times 0\times 0\times 0=0$. Merges? No. Consistent.

Case C — three pass, one fails (any position). Because multiplication doesn't care which factor is the zero, all four "three-out-of-four" cases collapse to the same verdict $0$. Failing tests is exactly as fatal as failing clarity. This symmetry is a feature: no factor is secretly optional.

Case D — the perfect PR. $1\times 1\times 1\times 1=1$. Merges. The only route to $1$.

PICTURE. The four corner scenarios side by side with their arithmetic.

---

The one-picture summary

The whole derivation in one image: four binary gates feeding a multiplier, one lit output. AND-logic made visible.

Recall Feynman retelling — say it back in plain words

Imagine you mail a box of code to a project. A guard checks four things, and only four: does it work, can I read it, are there tests, and did you solve the right thing? Each check is a light switch — on if the answer is yes, off if no. Now, how do I turn four switches into one verdict? If I add them up, then three good answers out of four looks like a decent score — but that's a trap, because a missing test alone gets you turned away at the gate. So instead I multiply the switches. Multiplying zeros and ones is just the word "AND": every switch must be on, because a single off-switch multiplies the whole thing to zero. Since each switch is at most a one, the biggest the product can ever be is one — that's the "perfect PR", the single lit cell out of sixteen. Every other combination — empty box, all-off, or any three-out-of-four — lands on zero. The reviewer's whole job during revisions is to walk around flipping off-switches back on until, at last, the product clicks to one and the gate opens.

Recall

Why multiply the four checks instead of adding them? ::: Multiplying $0/1$ values behaves like logical AND — any single $0$ zeroes the product, matching the fact that one fatal flaw makes a PR unmergeable. Adding would wrongly reward partial credit. What is the maximum value of $Q_{\text{PR}}$ and when is it reached? ::: $1$, reached only when all four checks equal $1$ (correct AND clear AND tested AND justified). Why must each $C$ be binary rather than a fraction? ::: A fraction would produce a fractional $Q_{\text{PR}}$ ("half-mergeable"), which is meaningless — the merge decision is yes/no, so the factors and the output must both stay $0$ or $1$. Of the $2^4=16$ combinations of the switches, how many give $Q_{\text{PR}}=1$? ::: Exactly one — the all-ones row. Which lifecycle step secures $C_{\text{justified}}=1$ before coding? ::: "Find Issue" — confirming maintainers want the change and it solves the right problem.

---

Connected reading

• Parent: Contributing to open-source ML
• The clarity factor in depth: Code Review Best Practices, Technical Writing for ML
• The tested factor: Testing ML Systems, Software Engineering for ML
• Getting a change into a branch at all: Version Control with Git
• Where PRs come from: ML Research Paper Implementation, Collaborative Machine Learning
• Why any of this matters for you: Building ML Portfolios