How to explain a pull request with a three-minute video

A reviewer opening a 30-file diff cold has to reverse-engineer your plan. Three minutes of you walking through it hands them the plan directly.

By the VeoRec team · Oct 3, 2026 · 12 min read

If you want to explain a pull request with video, the hard part is not the recording. It is deciding what to say in what order, so a reviewer gets the plan of the change in three minutes instead of spending twenty reconstructing it from the diff. Below is the order we use, with rough timings, followed by the small things that decide whether reviewers actually watch: which file to open first, where the chapters go, and where the link sits relative to the written description.

It assumes you already know when a video is worth recording at all. If not, start with code review with video, which covers when video helps review and when a line comment is better.

Know which pull requests deserve a video

Most pull requests do not need one. A typo fix, a dependency bump, a one-function bug fix with a test: a clear title and two sentences of description are faster for everyone. The ones that benefit share a trait: the reviewer needs a mental model before the lines make sense.

• Visible changes. A new modal, a changed checkout step, an animation, a CLI with a new prompt. Showing it running beats any number of screenshots.
• Changes with a shape. A refactor that moves logic between modules, a new abstraction with several implementations, a feature that touches the API, the worker and the frontend.
• Changes with a decision in them. You picked one approach over another and a reviewer might reasonably question it.
• Reviewers outside your context. Someone from another team, a new teammate, or a reviewer eight hours away for whom every question costs a day.

If your pull request needs more than about five minutes to explain, the problem is usually the size of the change, not the length of the video. Google's guidance on small changes suggests one self-contained change per review, with refactoring split from behaviour changes. Splitting first makes both the review and the video better.

Use the three-minute order

The structure below follows the order a careful reviewer reads a change anyway: first whether it makes sense, then the most important part, then the rest. Google's guide on reviewing a change describes exactly that order. Your video just does the first two steps for them.

The chapters for a real example, a change that batches price lookups in a checkout flow, would look like this. Click through to get a feel for how a reviewer moves around it:

Shift the time between sections for the kind of change

The four sections stay the same, but how much time each gets depends on what you changed. A UI change is mostly demo; a refactor has almost nothing to demo and needs a longer tour; a bug fix is mostly about the root cause.

For a bug fix, the "why" section can borrow from a good bug report: what happened, what should have happened, and how to reproduce it. If a video bug report already exists for the issue, link it in the description and skip reproducing it again in your own video; spend the time on the root cause instead.

Script it in bullets, not sentences

Reading a script aloud sounds like reading a script. Improvising with no plan produces "um, so, let me just find the file". The middle ground is a few bullets per section, written in the order above, open in a window next to the editor.

The three things to get exactly right are the opening sentence (the why), the context a reviewer needs, and the ask at the end. Type them into the planner below to see how long they take to say. If the hook and the ask together run past 40 seconds, cut.

A few bullets for the checkout example might read: "Big carts time out: one pricing request per line. Fix: batch up to 50 per request. Show 60-item cart before (8 seconds) and after (under 1). Start in PriceBatcher. Risk: what happens when one item in a batch fails? Want eyes on that." That is the whole plan. The post on how to script a screen recording goes further on bullet scripts.

Show the behaviour before the code

Most authors open the diff first because that is where their head is. Reviewers are in the opposite place: they do not know yet what the code is for. Thirty to sixty seconds of the change running gives them a reference point for every line they read afterwards.

What "running" means depends on the change:

• UI changes: click through the flow, including the empty state, the error state and the loading state. Those are the states reviewers forget to ask about.
• API changes: send a request with your HTTP client or curl and show the response. If the shape changed, show old and new side by side.
• Performance changes: show the measurement, not a claim. A timing in the network panel, a benchmark run, a query plan.
• Internal refactors: show the tests passing, and say plainly that behaviour should be identical. That sentence tells the reviewer what to check for.

If the change is in a web app, record the browser tab rather than the whole screen. It keeps the frame focused and avoids showing your other windows. If you want the reviewer to comment on specific parts of the page, record it as a Chrome tab in VeoRec; notes on a tab recording can stay attached to the page elements they point at, which helps when the reviewer is a designer or a product manager rather than another developer.

Walk the diff in reading order, not file order

Diff tools list files alphabetically or by directory. That order is almost never the order in which the change makes sense. A reviewer reading top to bottom might see test helpers, then a renamed type, then a config change, and reach the actual logic last, having spent their attention on the parts that do not matter.

In the video, take control of the order:

1. The file where the decision lives. Explain its shape: the new class, the new function, the changed algorithm. Do not read it line by line; say what it does and point at the two or three lines that matter.
2. The callers. Where the new code is used, and how the call sites changed.
3. The tests. What they cover and, more usefully, what they do not.
4. The mechanical changes. Renames, moved files, updated imports, regenerated files. Name them in one sentence and say they are safe to skim.

Select the lines you are talking about, or move the cursor to them and pause. Viewers follow the selection. Waving the mouse around while you talk leaves them hunting for what you mean.

Name the risks and the ask out loud

The last 30 seconds are the most valuable part of the video and the part people most often skip. Say what you are least sure about. "I think partial failures in a batch are handled, but I would like a second pair of eyes on the retry." A reviewer who hears that goes straight there.

Then say what you want from the review, and what you do not need. "I mainly want feedback on the batching; the type renames were done with the IDE and are mechanical." Reviewers spend attention where you point it. Point it nowhere and you tend to get twenty comments about naming.

Finally, mention how it is tested and anything you deliberately left out: "No migration needed. Feature flag is off by default. Follow-up for the admin view is ticket 913."

The same order for a one-line bug fix with a long story

Some of the best pull request videos are for tiny diffs. Say the fix is one changed comparison in a date helper, but finding it took two days because invoices dated the 31st were landing in the wrong month for customers west of UTC. The diff tour takes ten seconds. The why takes most of the video:

• Why (40 seconds): the support ticket, the invoice that showed up in the wrong month, and the time zone pattern that gave it away.
• Behaviour (40 seconds): the failing test written first, then the same test passing. Run them on screen.
• Diff (20 seconds): the one line, and why < should have been <= once the date is converted to the customer's zone.
• Risk and ask (30 seconds): "Anything else that calls this helper with local dates will shift too. I found three callers and checked them; can someone who knows the reports module confirm the fourth?"

Without the video, a reviewer sees a one-character change and either approves it blind or asks how you know it is right. With it, they know exactly which caller to check.

Expect reviewers to answer in two places. Line-level feedback belongs on the diff, as usual. Questions about something you said ("at 1:40 you said the batch size is fixed, but the config allows 100?") fit better as a comment on the video at that second, so the context is one click away. Whatever gets decided there should end up in the pull request thread too, in a sentence or two, so the reasoning is not stranded inside the video.

Add chapters so reviewers can jump

Even a three-minute video benefits from chapters. A reviewer who already knows the problem skips the why. Someone returning a day later to check the risk section jumps straight to it. A teammate reading the pull request six months later finds the diff tour without rewatching the demo.

The easiest way to get chapters is to mark them while you record, at each change of section. In VeoRec you press M (or use the toolbar), then name the markers on the finish screen; there is also a global add-marker shortcut, which is handy when your hands are in the editor. On Pro, AI chapters are generated after each recording if you would rather not mark them yourself. The chapter markers guide covers naming them well.

Name chapters after what the viewer will see, not after what you did: "Start here: PriceBatcher" is better than "Code walkthrough part 1". If you mention file names in chapter titles, reviewers can match them to the diff.

Put the video in the pull request the right way

Placement and framing decide whether anyone watches. Put the link at the very top of the description with its length, so reviewers know what they are signing up for. Below it, write the description as if the video did not exist.

The second part matters because a pull request is read for years. People land on it from git blame long after the review, and they will not watch a video to learn what a change did. Google's guidance on change descriptions asks for a short first line that stands on its own and a body that explains the problem, the approach and its limits. The video is extra, not instead.

Side by side, the difference is obvious:

If your team uses GitHub, a pull request template (a pull_request_template.md in the repo root, docs/ or .github/) can include an optional "Walkthrough video" line so authors remember the option exists without feeling forced to use it.

You can also upload a video file directly into a GitHub description. At the time of writing, GitHub's docs list .mp4, .mov and .webm with a 10 MB limit for repositories on free plans and 100 MB on paid plans (source). A three-minute recording passes 10 MB easily: even at a modest 1 megabit per second, 180 seconds is 180 megabits, or about 22 MB. An uploaded file has no transcript or comments, which is why many teams paste a link instead.

Record when the change is ready, and re-record when it changes

Record the video when you are about to request review, not while the pull request is still a draft that will change shape. A video describing code that no longer exists is worse than none, because the reviewer trusts it.

If review leads to a significant change of approach, re-record. It takes three minutes, and the alternative is a stack of comments saying "ignore the part at 1:40". Small fixes from review do not need a new video; add a line to the description instead.

A practical tip for the recording itself: do one silent dry run. Open the files in the order you will show them, run the demo once to warm caches and log in, and close anything you do not want on screen. Then record in one take. If you stumble, keep going; a natural correction ("sorry, the other file") is fine. If you badly lose the thread, restart rather than editing. VeoRec has a restart button for exactly that, and trimming the start and end in the browser takes seconds afterwards.

Avoid the mistakes that make reviewers skip the video

• Starting with "So, um, this PR is about..." Open with the problem in one sentence. The first ten seconds decide whether people keep watching.
• Reading the code aloud. The reviewer can read. Say why, and what to look at.
• Showing every file. Name the mechanical changes in one sentence and move on.
• Tiny, unreadable code. If the reviewer has to go full screen and squint, they will close it and read the diff instead.
• No mention of risk. A video that presents every part as fine invites the reviewer to find the problem you already knew about.
• A video with no description. It cannot be searched, skimmed or read from git blame.

Try it on your next pull request

Pick the next change you open that has a visible effect or touches more than a handful of files. Write the description first. Then write five bullets (why, what to demo, start-here file, what to skim, risk and ask), do a silent dry run, and record in one take with a chapter marker at each bullet. If you need a screen recorder for developers, VeoRec copies the link the moment you stop, so pasting it into the description is the last step, not a separate upload.

After the review, check one thing: did the reviewer ask fewer "what does this do?" questions than usual? That is the whole point, and it is easy to measure on your own pull requests.