How to Explain a Pull Request with a Video Walkthrough [2026]

A pull request walkthrough answers four things and then stops: what changed, why it changed, which flow in the running system it touches, and what it deliberately does not fix. Everything else is already in the diff, and your colleague can read a diff.

You are not writing anything new. All four answers exist already, scattered across the description, the linked issue and the review thread, in the order nobody will ever read them. The work is collecting them and putting the reason before the mechanism.

This guide runs the method through one real, public, merged change: pull request #23387 in the Vite repository. It also covers the half most guides skip: where a recorded walkthrough beats a written one, and the four things it is worse at.

Why the Diff Does Not Explain Itself

A diff is a complete record of what changed and a poor record of anything else. It is exact, it is machine-checked, and it will still leave a competent colleague guessing.

Three things a diff structurally cannot carry:

• The option you rejected. The approach you tried on Tuesday and abandoned leaves no trace in the merged code. Neither does the reason.
• The constraint that forced the shape. Code written to satisfy a reviewer, a deadline or a platform quirk looks identical to code written from first principles.
• The boundary you drew on purpose. A related bug you chose not to fix is invisible. To the next reader it looks like an oversight, and they will either fix it badly or file a duplicate.

Peter Naur made the general version of this argument in 1985: in Programming as Theory Building, a program is not its source text, and the working theory of a system lives in the people who built it. A pull request is that problem at its smallest and most fixable scale. The repository-scale version is a different method.

In the change below, a helper function exists in the merged code for one reason: a reviewer asked for it. Nothing in the final diff says so. The merged code is an answer, and the question lives somewhere else.

The Four Beats of a Pull Request Walkthrough

Treat the walkthrough as four fixed beats in a fixed order. Order matters more than polish, because a colleague who understands why can usually reconstruct how, and the reverse almost never works.

Beat 4 is the one that gets cut for time, and it is the one that decides whether the walkthrough is documentation or marketing. A change described only by what it fixes is a change nobody can safely build on.

Four beats fit in three to four minutes. Treat that as a constraint, not a target: a ten-minute walkthrough is nearly always beat 1 read aloud, with beats 2 and 4 missing.

A Worked Example: Vite Pull Request #23387

Vite inlines small assets at build time. Anything under build.assetsInlineLimit, 4096 bytes by default, is rewritten into a base64 data: URL so the browser makes one fewer request. For an icon, a clear win.

The pull request is titled fix(html): don't inline preload link targets (fix #13355). It was opened by kakiuwang-ui, then approved and merged into main by Vite team member bluwy on 4 September 2026. Five files, seventy-one lines added, eleven removed.

Beat 1: what changed

Three values were added to an existing set in packages/vite/src/node/plugins/html.ts:

const noInlineLinkRels = new Set([
  'icon',
  'apple-touch-icon',
  'apple-touch-startup-image',
  'manifest',
  'modulepreload',
  'preload',
  'prefetch',
])

The same change pulled the "should this be inlined" test out of an inline block and into a small getLinkShouldInline helper, so two separate branches of the HTML transform could call it.

Beat 2: why

A <link rel="modulepreload" href="/worker.js"> whose target was small enough got rewritten into a data: URL at build time. That looks harmless, and it is not. A data URL is a different module specifier from the emitted chunk, so the browser dutifully warmed a module nothing else on the page would ever request, while the real chunk arrived unpreloaded. A modulepreload pointed at the wrong specifier does not fail. It quietly does nothing.

The original report, Vite issue #13355, was filed in May 2023 and closed by this merge three years and three months later. Nothing crashed, no test went red, and the only symptom was a page slightly slower than its own markup promised. Silent failures survive because nobody is looking for them.

Beat 3: which flow it touches

Build only, inside the HTML transform. When Vite walks the attributes of a <link> element during a build, an href that was not a CSS request fell through to the asset processor with no inline decision passed in, which left it to the default size heuristic. The set of rels where inlining is always wrong already existed for icons and manifests. Preload rels belonged in it and were not there.

Dev server behavior and the JavaScript pipeline are untouched. The effect is visible in the built index.html.

Beat 4: what it does not address

Two boundaries, both stated by the author rather than inferred by us:

• The original issue also noted that the inlined file was the unminified original, meaning it never went through the JavaScript pipeline at all. The author calls that a distinct problem, tied to a separate issue, and explicitly out of scope here.
• <link rel="preload" as="style" href="x.css"> is untouched, because a CSS check earlier in the same function converts that link into a CSS import before this code ever sees it. Pre-existing behavior, deliberately left alone.

The half that is not in the diff

The first version of this change covered modulepreload only. The author had left preload and prefetch out deliberately, to keep the review small. The reviewer disagreed, in two lines:

I think we can fix these together. Can you add them in this PR?

Adding them exposed a second defect nobody had reported: the branch handling <link rel="preload" as="image" imagesrcset> called the same asset processor without an inline decision at all, so it never consulted the no-inline set. That is also why the merged code hoists the check into a helper, because the reviewer had asked for it to be computed only where it is used.

Two of the four beats came out of the review thread rather than the diff. That ratio is normal, and it is why a walkthrough built from the diff alone reads thin. Automated reviewers share the blind spot, which is one of several things they miss.

How to Write the Script in Ten Minutes

Six steps, mostly copying.

1. Write beat 1 as one present-tense sentence. "This adds the three preload rels to the set of link types Vite never inlines." If one sentence will not do it, the pull request is too big to walk through and should be split.
2. Lift beat 2 from the linked issue, not your own description. The issue is written by someone who hit the problem. Your description is written by someone who already understands it.
3. Name the flow in beat 3 by when it runs, not by file path. "At build time, while rewriting the HTML" tells a colleague more than a file name, and the file name is one click away.
4. Read your own review thread for beat 4. Every "I left this out because" and "that is a separate problem" belongs here. This is the step people skip, and the material is already written.
5. Cut anything the diff shows faster than you can say it. Nobody needs a renamed variable read aloud.
6. Say all four beats out loud once before recording. Anything you stumble over is a sentence you have not finished thinking.

A working opening for the Vite change, at roughly the right density:

Beat 1. This adds modulepreload, preload and prefetch to the set of
        link rels Vite never inlines at build time.

Beat 2. Before this, a small preload target got rewritten to a data URL.
        That is a different module specifier from the emitted chunk, so
        the browser warmed a module nothing on the page would request.
        Reported in May 2023, no error, just a preload that did nothing.

Beat 3. Build only, in the HTML transform. A link href that is not CSS
        fell through to the default size heuristic instead of checking
        the no-inline set.

Beat 4. The unminified emit in the same issue is a separate problem and
        is not fixed here. preload as=style never reaches this code.

You are not narrating the diff. You are supplying what the diff omits.

Recording It, or Generating It

Two routes, and the first needs no product at all. Open the pull request, share your screen, talk through the four beats, stop. Three minutes of your own voice over the diff beats most written handovers, and the only skill is not editing it afterwards.

The second route is generating it. Scrimba Explain, listed in the ChatGPT plugin directory as Explain Video Generator, turns a question into a narrated explainer and is free during open beta. A pull request walkthrough is one of the three example uses Scrimba promotes on its own store listing, quoted here exactly as it appears there:

Create a video tutorial of this pull request to help my colleague understand it

Explain has four documented routes, and they are not interchangeable for this job:

Adding the MCP route is the same setup as any other server, and the product guide covers the rest.

One requirement trips people up. The plugin has to be installed before its name does anything. Typing the name into a ChatGPT session that has not installed it returns an ordinary text answer, indistinguishable from asking without it. OpenAI's own documentation puts availability down to your plan, region, workspace, role, model and interface, so install first and confirm the plugin actually fired.

A note on what this guide is and is not showing you. Scrimba publishes a public gallery of roughly 150 explainers with named authors, runtimes and view counts, which is real evidence the product ships finished explanations. Those are general topics rather than pull request walkthroughs. The pull request case is documented by the vendor, not demonstrated here. Run one on a change you already understand before relying on it for one somebody else must inherit.

What a Video Walkthrough Is Bad At

Four failures worth knowing before you standardize on it:

• It is not searchable. Six months later somebody greps for noInlineLinkRels, finds the code and the tests, and your explanation sits inside a media file.
• It is not diffable. When the code changes the walkthrough does not, and no reviewer will ever be asked to approve an update to it.
• It has no stable anchors. You cannot link a colleague to the sentence about the imagesrcset branch, only to a timestamp, which drifts the moment anyone re-records.
• It goes stale silently. A stale comment at least sits next to the code contradicting it. A stale walkthrough sits in a channel looking authoritative.

The working split: video carries reasoning, text carries reference. Reasoning is stable, because why a change was made does not change when the code is refactored. Reference goes out of date the moment anything moves, which is why it belongs in the documentation layer where it can be regenerated.

Write instead of recording when the thing must be greppable, when a compliance reader will read it, or when the code changes weekly.

Where the Walkthrough Should Live

Ranked by how long it survives:

1. The pull request description, linked at the top. It stays attached to the change, and repository search finds the PR even when it cannot find the video.
2. The merge commit body, for changes that alter a flow permanently. git log is the one place a future reader is guaranteed to look.
3. The team channel at merge time, for reach. That is distribution, not storage: a link posted only in chat has a half-life measured in days.
4. The onboarding doc, but only for changes a new joiner must understand before they can work. A library nobody prunes is worse than none.

Name it with the pull request number in it. vite-23387-preload-inlining is findable; walkthrough-final-v2 is not. If your team is still settling these conventions, the basics of Git and GitHub cover where each one lives.

Frequently Asked Questions

How do you explain a pull request to a colleague?

Cover four things in order: what changed in one sentence, why it changed, which flow in the running system it touches, and what it deliberately does not fix. The material already exists in the diff, the linked issue and the review thread. Put the reason before the mechanism.

How long should a pull request walkthrough be?

Three to four minutes, roughly a minute per beat, which is short enough that the last beat survives. Anything past ten minutes is usually beat 1 read aloud line by line, with the reasoning and the scope boundary missing.

Can AI generate a video walkthrough of a pull request?

Yes, and it is a documented use rather than a workaround. Scrimba Explain, listed in the ChatGPT plugin directory as Explain Video Generator, promotes exactly this on its store listing and is free during open beta. For a pull request the MCP route through a coding agent fits best, because the agent already has the repository in context. Install the plugin first: an uninstalled mention returns an ordinary text answer.

Is a video better than a good pull request description?

Neither replaces the other. A description is searchable, diffable and linkable, so it should carry the reference material. A walkthrough carries the reasoning, which is what a written description compresses out under time pressure. Do both: record the reasoning once, keep the description as the index.

What should a pull request walkthrough leave out?

Anything the diff shows faster than you can say it: renamed variables, formatting, mechanical refactors, style opinions. What must never be cut is the scope boundary, the only part telling the next person what is still broken.

Key Takeaways

• A pull request walkthrough answers four things: what changed, why, which flow it touches, and what it deliberately does not fix.
• Beat 4 is the integrity test. A change described only by what it fixes leaves the next reader unable to tell a deliberate boundary from an oversight.
• The review thread carries material the diff cannot. In the Vite example, both the widened scope and the extracted helper exist because a reviewer asked, and the merged code says nothing about it.
• Video carries reasoning, text carries reference. Reasoning is stable. Reference goes stale the moment the code moves, so it belongs somewhere greppable.
• A generated walkthrough needs the plugin installed first. Mentioning Explain Video Generator in a ChatGPT session without it returns ordinary text, which reads like the product doing nothing.

Sources

• Vite pull request #23387, merged 4 September 2026
• Vite issue #13355, Cannot preload workers, opened May 2023
• Vite build options, build.assetsInlineLimit
• MDN, rel=modulepreload
• Peter Naur, Programming as Theory Building, 1985
• Scrimba Explain and the public explainer gallery
• Explain Video Generator, ChatGPT plugin directory
• OpenAI, connectors in ChatGPT

Accessed September 2026.