Yoav's blog thing

Mastodon   RSS   Twitter   GitHub  

So, you want to push a web platform feature?

“If you give the same advice more than twice, write a blog post!” - Abraham Lincoln

Over the years, I’ve helped a few folks get into browser development, and tried to encourage many others. In that process, I found myself giving similar advice, again and again.

This is my attempt to have somewhere I can send browser-curious folks to. So, in this post, I’ll try to outline why you may want to contribute to browsers and how you may go about doing that. I hope some of y'all may find it useful.

# Why

As a web developer, having the ability to change the web platform is a super power. It enables you to influence the landscape in which you and your team operate, and change the platform on which you build. That can enable you to achieve things that weren’t feasible before, or were super complex.

One example from my past is the implementation of preload and preconnect in Chromium and WebKit which enabled Akamai (my employer at the time) to build an Adaptive Acceleration product and improve its customers’ performance. Another is ES module integrity, which enables Shopify to use ES modules in its PCI compliant surfaces.

Many years ago, I wrote about why I contribute to Chromium and the web platform, and why I think you should too. All these reasons still stand:

Overall, I think that a healthy way of thinking about pushing features on the web platform is a mix of "giving back" ideology and selfishly making the things you (or your employer) want or need to see happen. The latter part helps to make sure your contributions are sustainable.

# How

Ok, now that you're surely convinced, what's the first step?

# Find a you-sized problem

The most open-ended part of this journey and arguably the hardest one is deciding what you should be working on.

The web is vast and has many issues and missing features.

There are a few good first bug lists (at least for Chromium), and they are a great way to "exercise" the build pipeline and see that your computer is set up, and you have a clear understanding of how Chromium commits get made.

But in some ways it might be better to start with a small feature you'd love to see in browsers. I find that personal motivation to see a problem through can help surmount the occasional hurdle that may find you along the way. (computers, amirite?)

The emphasis here is on “small”. Starting off with your own proposal that paves new ground may be playing web standards in hard mode. You’d need to spend a lot of time and energy convincing people that the way you’re proposing to solve the problem is indeed the right way. If you go that route, get ready for a bumpy ride and lots of iterations on what the solution should actually be like.

If you have a hard time finding a small problem you’re interested in tackling, feel free to ask folks that are working on areas you're generally interested in. There are always more problems lying around than people with time to tackle them.

Most importantly, if you don't know who to ask regarding problems to tackle or where to gather feedback on your proposal ideas, feel free to reach out and I can help with intros! :)

# Standards

Once you found your problem, depending on the level of agreement on what the solution should look like, you may need to discuss it in a standards venue.

But first, what are "standards"?

To quote Alex Russell from his article on standards work:

# “Standardisation is the process of documenting consensus”

Standards are there to document what browsers have implemented or are implementing, to ensure interoperability and so that future implementations have a clear path they can follow.

From the above you can also understand that standards are not there to force browsers to implement something. Getting some text into a “standard” means nothing if you can’t also convince implementations they want to follow it.

# Standard venues are just venues

Standard venues are places where competitors can gather and discuss ways they can collaborate on industry standards in a legally-safe way. That means that the W3C, WHATWG, Ecma or the IETF don’t do any work to move the web platform on their own. They are just there to enable engineers from different (and potentially competing) parts of the industry to do that.

The nature of these discussions is… interesting. On the one hand, we’re putting competitors in a room to discuss features they may have misaligned incentives about.

At the same time, most of the folks that have been doing this for a while are part of “team web”, some have worked for more than one browser vendor, and are there because they want to push the long-term vision of what they believe is best for the web.

There are multiple different venues for web platform browser work. Javascript features are being worked on at Ecma’s TC-39.

HTML, Fetch and other "infrastructure" features are being worked on at the WHATWG.

And many other features are being worked on in the many W3C Working Groups (e.g. CSSWG, WebAppSec, WebPerfWG) or in incubation Community Groups, such as the WICG.

For some of those discussions, you’d need to become a member of the relevant standard venue. For example, joining the WICG requires a W3C account. Joining WG calls may require your employer to become a member (which incurs fees that vary based on your employer’s size) or the WG chairs to invite you as a guest or an Invited Expert. So there’s some red-tape involved.
Incubation venues are typically lighter on process, and the process gets heavier as proposals progress on their way to become standards.

# Why should browsers care?

If getting some text into a spec does not make it a standard, what does make a standard? And why do browsers implement standards at all?

Well, browsers need websites to work in them, because otherwise users would switch to another browser where they do. The interoperability that standards enable helps ensure sites are working in different browsers and developers can adopt new features. That’s why browsers voluntarily comply with standards that match some implemented reality. Aspirational specification doesn’t have those dynamics, so writing down fiction in a “standard” has no effect.

As I alluded to above, moving from a specification to a standard requires consensus. You need multiple vendors to agree a certain document is now a standard they intend to follow in order for that document to transition from a specification to a standard. There’s often a bunch of red-tape involved in that transition that I won’t bore you with now.

# Getting involved

The working modes between the different groups and standard venues can be slightly different, so if the feature you want to push already falls under any particular group, it's worthwhile to read up and understand how it operates.

But in general, most of the work on standards simply happens on Github, similar to any other open source project. So for any areas that are potentially of interest, you probably want to find the relevant GH repos, subscribe to interesting discussions and chime in. This will also help you understand what features are already being worked on, who is pushing what, etc.

Getting involved and being generally helpful (e.g. take on chores, find and fix broken things in the specs, etc.) can go a long way to help you build relationships with the existing community and get some "street cred" as someone who knows what they are talking about.

You should also not be shy about opening issues regarding things you want to push, in order to gather opinions on them. At the same time, you want to make sure you're doing that after you get some understanding of the spec, its different moving parts and how your suggestions fit in.

Finally, for shipping things in the platform, you need to eventually file PRs to sketch out the changes you want to make relevant specifications, iterate over them and eventually land them in the standard. (e.g. this one)

# Tests

Tests for most things in the platform (other than Javascript and network protocols) are covered by the web-platform-tests test suite. Simon Pieters gave a great intro talk on writing such tests. You should probably watch it.

Broadly, the tests are written using HTML, CSS and JS, with an occasional sprinkle of Python for the backend. The tests are running a common testing framework, and are used to exercise different web-exposed parts of the platform and to make sure they behave as expected.

If you’re coming from a web developer background, writing WPTs (as the cool kids call them) should make you feel right at home. The framework and style requires a bit of getting used to, but nothing beyond that.

It's probably a good idea to start out by sketching some tests for your feature/bug and see how you expect it to behave.

# Implementations

Now to the most interesting part - turning your ideas into running code!!

Both Chromium and WebKit (which are the engines I have experience with) are huge codebases, where you can get lost easily.

One way to tackle this is finding a minimal area of interest - If I want to change one bit of functionality, I e.g. find the class that implements that bit and only try to understand that specific class, or a smaller part of it, if it's a large one. Essentially, I try to get the minimal amount of understanding that would enable me to implement the change I need to get done. Then, over time, I try to expand my "circles of understanding" and get a better understanding of the surrounding data flows and code. At the same time, I also try to work from the outside in - get some high-level understanding of the broader architecture and flows.

That helps me close the gap between those two extremes over time.

# Chromium

# Building

The first step towards starting to contribute to Chromium is getting a setup going. Monica Dinculescu wrote the ultimate post on that. It’s not very recent, so some things may be a bit out of date, but it’s still a great resource! Otherwise, the official documentation is a bit less fun to read, but up-to-date and accurate. In particular, you don’t want to miss the “faster builds” section (mac/linux).

Before I had REClient access, I developed a few habits that helped me get around the (extremely long) build times. You may want to adopt some of them:

# Getting around

Once you’ve got a setup going, one of the best tools to get familiar with is chromium’s code search. It’s the absolute bestest. You will get spoiled by it and begrudge every other code search solution out there. You have been warned!

Code search will enable you to find areas of the code that you’re interested in, and enable you to hop from a function to its callers, overrides, etc. Clicking through it will help you build a mental model of the relevant code and its flow.
“Blame” view can also help you find relevant CLs (SVN-lingo for PRs) that potentially do similar things to what you’re trying to do. Copying Getting inspired by an existing CL is a great way to tackle your first contribution, without being overwhelmed.

At a higher level, you probably want to understand Chromium’s processes and what kinds of red tape you have to go through to ship features there. The official docs are there and reading through them can help. I also gave a talk as part of the Chromium University on what’s involved.

# Getting help

The best way to reach out to fellow Chromium contributors is in the Chromium Slack. It’s a bit light on participants, but there are enough helpful folks there to get you unstuck if (read: when) you’d hit some error you don’t get or have general questions about the code.

Unfortunately, access to that Slack is limited to folks that are already in the AUTHORS file, so people who already contributed some code. That’s a bit backwards, as one typically needs the largest amount of help before their first contribution. Oh well..

The best alternative to Slack if you don’t yet have access is the chromium-dev mailing list. Feel free to ask naive questions there. People there are typically super nice and will help you out.

# Getting stuff done

By now you have a working setup and a problem you want to tackle! That’s a great start.

But before you get started, you may want to validate with the relevant code owners that the thing you want to get done is something they’d support. If it’s a bug fix, you can comment on the bug saying you want to tackle it, and ask for feedback on your plans.

If it’s a larger feature, probably the best way to get feedback on it and your plans is to send an intent to prototype email to blink-dev.

You can get one started through Chromestatus. You can get a feature there going, fill in the details and it can automatically generate an intent email for you.

That’s also approximately the time you want to kick off a TAG review (example) of your design or spec, as well as WebKit and Mozilla positions (example). That would help you gather feedback from various industry stakeholders, with enough time for them to respond and for you to potentially pivot your solution based on their response.

Otherwise, blink-dev is generally a good mailing list to subscribe to, to know what others are working on, and get a better feel of the general vibe of intents and their reviews. That can probably help you know what to expect when you end up writing intent emails yourself.

In parallel to that, it might be a good idea to sketch out the design for your feature. For example, when tackling multiple import maps, I started out by talking to Jake Archibald and putting together a design doc.
I then ran it by relevant folks and continued the design discussions as part of the HTML PR, and eventually started mapping spec concepts to code pointers, which helped me to start prototyping the feature. I did that mapping using codesearch by searching for relevant spec links. But if you’re having trouble getting started, the relevant code owners may be able to help. Don’t be afraid to ask them.

Once you have all that mapped out, and folks don’t think it’s an awful idea, you can start implementing!

Write relevant code, build it, test it, see that it doesn’t work and fix it! Rinse and repeat!!

Web-platform-tests (see above) are a great way for you to do the “test” part of the feedback loop above, and are something you’re going to need anyway in order to ship your feature. So you might as well write them now!

The nice thing about writing WPTs as part of your Chromium process is that nice robots automatically export them to the cross-browser repo, with no further work on your part (if all goes well and your tests aren’t flaky on other engines).

A few random notes:

Once your implementation is working (example), well-tested and relevant people agree that it’s a useful platform feature and it’s solving the problem the right way, you can probably ship it. You can do that by sending an intent to ship, get 3 LGTMs from the API owners as well as approvals from the various cross-functional reviews (Privacy, Security, Testing, Debugging, Enterprise, etc).

Once all the approvals are in place, you can flip the feature flag to enabled by default (e.g. like that), and the feature will be live in future stable Chromium releases. (you can tell which based on the branch date in the “schedule” dashboard)

Obviously, there are a million details I’m leaving out here, but hopefully the above gives you a clear mental model of the path you need to walk through.

# WebKit

By now you have the spec, tests and Chromium implementation done. Hooray!!

As part of Chromium’s shipping flow, you probably already sent a WebKit position. That enables the WebKit folks to voice their opinions on the feature. Assuming that their opinion is a positive one, what’s better than to also ship your feature in WebKit?

# Building

Building WebKit is less of an ordeal compared to Chromium, and full rebuild times are significantly smaller, partially thanks to their use of unified builds.

The downside is that incremental build times can be slower, making local iteration cycle round-trip-times slightly higher.

Instructions for getting the code and building WebKit are not complex, especially if you have a Mac. If you’re on Linux, WebKitGTK is your best bet.

A few paper cuts I ran into:

# Getting around

WebKit’s contribution flow is likely to feel more familiar than Chromium’s as it all happens in good ol’ GitHub, at least to a large extent. The only exception is that issues are still being tracked in Bugzilla.

As a result of that, you can simply use GitHub’s search in order to find the code you’re looking for.

But because GH search leaves much to be desired, the good folks at Igalia have set up their own WebKit search engine. It’s pretty good, but it’s… not Google’s code search that chromium has. Way better than GH search though.

# Getting help

WebKit Slack is open for anyone to join, and the #help and #dev channels there are very useful. Webkit’s mailing list is mostly used for announcements by the team, and less for asking questions, but can still be a useful resource to follow.

If you get stuck on some configuration, build or architecture issue, folks there would be happy to help you out with pointers if they can.

# Getting stuff done

Similar to Chromium, the way I like to tackle features in WebKit is by looking for relevant spec links in code search, to try and find relevant pointers. If I’m lucky, the code is already annotated with spec links, and that helps me find the hooks I need to add the new feature.

In general, WebKit’s code is tighter, as they are using more cutting-edge C++ features compared to Chromium. It’s also often modeled closer to the spec, which makes it easier to “translate” English into C++.

On the downside, code comments are sparser and classes don’t often have documentation of what they do and why. The ubiquitous use of auto also makes it nicer to write code, but harder to read it.

Unlike Chromium, there’s no automatic rewrite of your code to match WebKit’s (different) style, but you do have a linter that runs at upload time and yells at you when you get it wrong. Once it does, you need to manually fix your code’s style, like an animal.

Regarding tests, there’s no automatic import and export, so you’d likely need to manually import your tests. I like to do that as a separate PR (while adjusting the test expectations to fail), with the feature’s implementation PR coming after that, fixing the test expectations.

The git flow for WebKit is.. unique. Basically, every PR has to have a single commit, and as you evolve it, you change your code, and then git add . && git commit –amend . I’m not a fan, as you lose the past state of your PR, but I guess it works.

Unlike Chromium, there’s no particular process for shipping other than a WebKit reviewer approving your PR and landing it. (example)

# Parting thoughts

That was a lot, wasn’t it?

Well, it is a lot. Getting into browser dev is not for the faint of heart, and is a time-consuming ordeal. But like I said above, I think the web is important, and it’s on all of us to keep it thriving. Plus it’s super fun!

If you’re planning to tackle this journey, I’m always happy to chat a bit and do what I can to help you get started. Feel free to hit me up!

P.S. I can hear you thinking - “what about Firefox?!?!???”

Unfortunately, I don’t have much experience there. But I hear good things, and other folks have written about getting started there.

Thanks to Keith Cirkel, Gal Weizman, Brooks Lybrand, François Beaufort, and Anne van Kesteren for their review and feedback on an earlier version of this post.

← Home