Screen recordings for READMEs, pull requests and bug reports

A ten-second clip explains a UI change faster than a paragraph, and it settles a bug report that words cannot. On GitHub you drag a GIF or a video into an issue, a pull request or a comment, up to 10 MB for a GIF and 10 or 100 MB for a video, depending on the plan of whoever owns the repository. A README is different: it shows a GIF committed to the repository, and anything longer is better linked than embedded. The rest is craft: one change per clip, cropped to the window, short enough to watch twice. The worked example here is Focal, a screen recorder for Windows, but the rules hold for any recorder.

My name is Vince. I make Focal, and I have posted my share of clips that explained nothing to anyone, including me a week later. That is how I came to have rules about them.

What GitHub accepts in issues, pull requests and comments

I checked GitHub’s page on attaching files on 2026-11-02. The mechanics are what you would guess: drag a file into the comment box to attach it, or click the paperclip below an issue comment box or in the formatting bar above a pull request comment box. In many browsers you can also paste an image straight in.

Images and media are accepted everywhere you can attach a file: PNG, GIF, JPEG and SVG, and video as MP4, MOV or WebM. The size limits on that page:

• Images and GIFs: 10 MB.
• Videos, in a repository owned by a user or organization on a free plan: 10 MB.
• Videos, in a repository owned by a user or organization on a paid plan: 100 MB. Above 10 MB you need to be a member of that organization, an outside collaborator, or on a paid plan yourself.
• All other files: 25 MB.

Two more lines on that page deserve your attention. Whether a video plays depends on the browser’s support for its codec, and GitHub recommends H.264 for the widest compatibility, so export H.264 rather than HEVC for anything you attach. And files uploaded to a public repository can be opened without signing in. Look at the whole frame before you post: a token in a terminal, a name in a sidebar, a notification in the corner. Code review goes over the diff line by line, and nobody reviews the corners of a GIF, so that part is yours.

What a README can show

GitHub’s guide to basic writing and formatting shows how to display an image in a Markdown file, and says to use a relative link when the image lives in your repository. GitHub counts a GIF as an image, so a README shows one the same way: commit it, to docs/demo.gif for example, and point the image link at that relative path.

Video is where GitHub’s documentation goes quiet. It describes uploading video to issues, pull requests and comments, and I found nothing there about a video in a README, so I do not build on one. The README gets a short GIF of the main idea, and a line under it links to the full MP4 where it already plays: the pull request that shipped the feature, an issue, or a page on your own site.

Keep that GIF small. It loads with the page, and once it is committed every clone of the repository carries it, even after you replace it. A 40 MB GIF merged in a hurry is downloaded by every contributor who ever clones the repository, long after the screen it shows has been redesigned. The guide to making a GIF of your screen on Windows goes further into GIFs.

What makes a clip useful in a pull request

A reviewer has the diff on one side and one question: what does this look like now? The clip answers that and nothing else. It is a screenshot that moves, not a trailer. These are the rules I would give a colleague:

1. One change per clip. If the pull request changes two things, record two clips and put each next to the paragraph that describes it.
2. Crop to the window. A whole desktop shrunk into a comment column is unreadable. Record the app’s window, or only the page in a browser, and the change is big enough to see.
3. Match the repository’s screenshots. If the README shows the app in a light theme, record in light. A dark clip next to light screenshots looks like a different product.
4. Show the keystroke when the shortcut is the point. A clip of a new command palette that never shows Ctrl+K being pressed leaves the reviewer guessing. A small pill with the combination settles it.
5. Hide an idle cursor. A cursor parked where you last clicked sits on top of the thing that changed. Move it away, or use a recorder that fades it out when it stops.
6. Zoom on what changed. A one-pixel border fix is invisible at full window size. Zoom in on it, hold, and come back out.
7. Under ten seconds for a GIF. A GIF has no sound and grows quickly with every second. Past ten seconds, or as soon as you want to talk over it, export an MP4.

What a bug report clip should show

A bug report clip has a harder job than a pull request clip: it has to show the way to the bug, not only the bug. Start from a state anyone can reach, a fresh page load, a new file, the app just opened. Show the version on screen before the first step, in the About box, the footer, or the output of the version command in a terminal. Then do the steps one at a time, at the pace of someone seeing them for the first time, not someone who has reproduced the bug forty times this morning. Hold on the wrong result for a second or two so nobody mistakes it for a frame that flashed by. Bug clips usually run long, so make them MP4s.

In the text of the issue, write the steps as a numbered list, what you expected, what happened instead, the version and the version of Windows. The clip proves the bug, and the words make it searchable. A maintainer looking for duplicates searches text, not frames.

One Windows catch. If the app you are reporting on runs as administrator, its clicks and keys are hidden from Focal unless Focal also runs as administrator. Focal warns before you record such a window, and the editor marks that stretch of the recording. Click zooms and keystroke pills need those clicks and keys, so for an installer or an elevated tool, start Focal as administrator for that recording, or accept a clip without them.

Making the clip with Focal

Focal sits in the system tray, out of the way. The whole routine is six steps:

1. Snap to the window. Press Print Screen (or Ctrl+PrtSc, if another program owns Print Screen, and Focal says so), then click the window. For a web app, Focal can leave out everything but the page in Chrome, Edge and other Chromium browsers, or leave out an app’s own title bar, and it remembers the choice per app.
2. Set Keystrokes to Shortcuts. Key combinations such as Ctrl+C and function keys then show as a pill at the bottom or top of the video, timed with cuts and speed changes. Focal keeps that choice for next time. Everything shows all typing, for one recording only, but that recording’s input log keeps every key, passwords included, and Focal warns before that project is exported or shared. For pull requests and bug reports, Shortcuts is the setting.
3. Record the one change. After the countdown, do it, then stop from the control bar.
4. Check the zooms. The editor opens with zooms already made from your clicks. Delete one that does not help, or press Z to add one on the thing that changed. The cursor is drawn after recording, so it fades when idle and comes back when you move, stays sharp at any zoom, and can be light or dark to match the theme.
5. Trim. Cut the start and the end on the timeline down to the change, or press I and O around it and export only that part, keeping the whole take for later.
6. Export. Use the GIF preset for a README or a short silent clip, or MP4 with H.264 for anything longer or with your voice.

Focal has no cloud and no share links, so the exported file goes into the comment box the same way as any other file. If you make clips for the same repository often, save the background, padding, corners and cursor as a Style and set it as the default, so every clip matches the last one.

When a colleague should change the clip rather than only watch it, open the Projects window and pack the recording into a single .focalproj file. If they have Focal, a double-click imports it, and because the cursor, clicks and keys are kept as data rather than pixels, they can still move a zoom, resize the cursor or trim it differently. It is the nearest a video gets to a suggested change. Someone without Focal needs the exported MP4 or GIF.

For a walkthrough longer than a pull request needs, with your voice and captions, see how to record a coding tutorial on Windows. Focal is free to record and edit with every feature, with no time limit, no card and no account. Exporting the GIF or the MP4 needs a license, and until you enter a key the editor’s preview shows a “Made with Focal” watermark.