2024 Wrapped: MDN Web Docs, HTTP content, GitHub maintenance, Firefox release notes.

It’s that time of the year again - 2024 is ~~coming to a close~~ wrapped. Let’s look at what I did over the last year on GitHub. I’ll share some stats that I collected from my work, visualize the data to understand it a little more, and show the categories and types of work I focused on.

MDN GitHub PRs in 2024

A lot of the work that goes into keeping MDN running happens in our GitHub organization, which has about 40 active repos. As is tradition, let’s have a look at the count of my PRs in these repos each month:

March 2024 was the busiest month in terms of PRs opened, with a total of 35 PRs landing (down from the 44 I made in August 2023). May and October 2024 seemed like they were quiet enough, but as usual opening PRs is not everything we do. There’s a lot of housekeeping of the GitHub organization, discussions, our other online community spaces, etc.

Get this data

You can get this data (at least the public bits) yourself using the gh CLI:

gh api --paginate \
  "search/issues?q=author:bsmth+org:mdn+type:pr+created:2024-01-01..2024-12-31" \
  --jq '.items[] | [.title, .number, .state, .html_url, .created_at] | @csv' \
  > 2024_bsmth_prs.csv

PRs by repository

I created 274 PRs across 23 public MDN GitHub repositores in 2024. This is slightly lower than last the 281 PRs in 25 repositories from 2023, but it’s actually surprisingly close. Usually, I’m working on mdn/content and mdn/browser-compat-data repos, but in 2024, I did a lot of editing on the MDN Blog. After the blog, the shared-assets repository was the number 3 repo that I contributed to, and I’ll go into more detail on that later.

The year of conventional commits

I first started trying conventional commits to make my PRs a bit more structured somewhere around 2021. Over the years, I see more and more projects using this as a way to generate release notes and otherwise categorize changes, so I do this regularly now. In 2024, I did a lot better at sticking to this pattern. I’ve said it before, it’s hard to use conventional commits when you work on a documentation project - everything is docs: on MDN, so I have used relnote: for Firefox, and a scope like docs(http): for technology categories.

Here’s a breakdown of the types and scope of MDN PRs in 2024:

It appears I’m a fan of chore: commits, and that’s a bit of a catch-all for “maintenance”, but there’s a lot of it, so it deserves to be noted. This chart also highlights that HTTP was the biggest technology category I worked on, which is a relief, because it was my goal for Q3 and Q4 in 2024, which I’ll go into in the next section. PRs using feat: are usually additions of pages or code, so there was a good amount of new content added for HTTP docs.

2024 goals and themes

I had three main goals that my work was guided by:

MDN HTTP documentation
Maintenance & chores
Firefox release notes

Let’s take a look at these categories, what they are, why they’re important, and a few highlights from each.

MDN HTTP documentation area

I wrote a good summary of these changes for the MDN 2024 recap. It’s a topic I love, because HTTP is what keeps the web humming, powering data exchange between people, servers, browsers, and machines.

MDN’s HTTP section has over 300 pages, made of 61 response status codes (like 200 (OK) or 418 (I’m a teapot)) and 148 HTTP headers for sending metadata and instructions back and forth, including Content Security Policy and Permissions Policy. Guides describe HTTP’s evolution from version 0.9 to HTTP/3, covering topics from basic usage to crucial mechanisms like caching.

The main point of the HTTP work was to update and improve examples, remove obsolete content, and standardize formatting across the entire section. I didn’t get to everything, and there’s some stragglers still on my list to fix (HTTP/1.1-specific concepts) but I’m very happy with the progress, and the positive feedback from our readers is up 10% (absolute) in this section since I started.

In the MDN summary post, I highlighted the Server-Timing HTTP header as interesting, you can use to surface server metrics to a client:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 123
Date: Fri, 03 Jan 2025 10:41:21 GMT
Server-Timing: custom-metric;dur=123.45;desc="My custom metric"

--- response body ---

For example, the BBC iPlayer is using the Server-Timing header to send performance metrics about the service, visible in the Network > Timings panel in Firefox. The main point of sending these metrics is to grab them via the Server Timing API so you can act on server-side metrics in the same way as all the other metrics processed with the Performance API.

Seeing as I’m going all-in on charts this year, here’s my HTTP-themed PRs:

Most of the work was adding content (feat), and tidying up and fixing docs (chore), but there were some release notes for Fx 132 that were interesting to work on, too.

Reading: For brushing up on HTTP topics, I enjoyed HTTP/2 in Action by Barry Pollard (@tunetheweb). If you’re familiar with HTTP/1.1 and want to dive into how the successive protocol(s) work, I can really recommend the book. Sending a big thanks to Barry.

Mermaid diagrams and shared assets

I’ve championed SVG and mermaid syntax for sequence diagrams on MDN, mostly for maintenance reasons, as it makes it easier to store sources for images that we usually need to update later. Binaries and images in documentation are something to be really careful about adding, because they very often cause heartache. The worst offenders in docs are screenshots of code or screenshots of products or software UIs.

There’s typically always a better alternative than screenshots. For code, add actual code blocks to your prose so you can detect, lint, spellcheck, and update them easily, among other reasons. For product screenshots, like guides on setting up hosting on a specific provider, these go out of date almost instantly - official documentation is usually better to link to instead. I try to stick to SVG, where possible, but there are always exceptions (like fancy interactive diagrams), so it’s also good to be flexible when needed.

I pushed a lot for images to be stored in a shared-assets repository, which allows us to reuse images instead of duplicate them in the source, and these are easier to write, read, maintain, and they look nice, too.

GitHub chores & maintenance

As usual, there’s a ton of ad-hoc, unplanned work that keeps us extremely busy. We try very hard to keep up with everything that’s happening in the MDN GitHub organization, which includes moderating issues, pull requests, and discussions, replying to questions, talking to our community, partners, readers and contributors. I hope we’ve managed to keep MDN inviting for people to learn and contribute, as well as engaging to work on for new and long-time collaborators. We all love maintaining MDN as much as people love reading it, so I hope that shows.

Firefox release notes

The MDN team document each Firefox release with release notes specifically for developers. You can find everything in the Firefox release notes for developers pages. We also document Experimental features in Firefox for things that are only available behind a preference (though configuration). This might be interesting if you’re looking to try out new features before they’ve landed in stable releases. One of the notable changes was documenting that HTTP/2 Server Push is now deactivated by default in most major browsers.

Writing about the web

Lastly, these are things I wrote about on the MDN blog:

Getting hands-on with Rust

In February 2024, I took a 3-day “Introduction to Rust” course run by Florian Gilcher of Ferrous Systems GmbH. My prior experience was documenting a Rust client for a time series database, and refreshing the Compiling from Rust to WebAssembly tutorial on MDN. In the course, we built a TCP server which was challenging, but great fun. I learned a lot, and I plan to put some of this to use in MDN’s new build system, rari.

That’s a wrap

We made it to the end of my 2024 wrap-up post. I want to send a big thanks to Ruth John and the rest of the MDN team for the support and guidance all year. I wouldn’t have landed all my HTTP work if it wasn’t for Hamish - thanks for the patience!

Thanks a lot for reading, and let me know what your thoughts are, if I missed something, or if you have any other suggestions. Feel free to get in touch on Bluesky.

Published: January 11, 2025