How I Submitted My First WordPress Core Patch (And What I...

I always assumed contributing to WordPress core was for people with decades of open source experience. Senior engineers. People whose names you recognize in commit logs.

Turns out I was wrong. I submitted my first patch this week and the process was more straightforward than I expected. Not easy — but straightforward. Here is exactly what I did.

Finding a ticket worth working on

The first thing I learned is that most open tickets on Trac are not actually patchable. Either someone recently said they cannot reproduce the bug, or the fix requires a design decision that core committers have not agreed on yet, or the ticket is so old nobody cares anymore.

I filtered Trac for:

Status: new
Keywords: needs-patch
Component: REST API
Type: defect (bug)

I looked at three tickets before finding one worth touching. The first two had recent comments saying the bug could not be reproduced. I walked away from both immediately. Never spend time on a ticket where someone recently said "can't reproduce" — it is a dead end.

The ticket I picked

I landed on #48257. The bug was a REST API discoverability problem in the media upload endpoint.

When you POST to /wp/v2/media and the server runs out of resources mid-upload during image sub-size generation, WordPress sends an X-WP-Upload-Attachment-ID header back to the client. This tells the client the attachment ID so it can retry via the /post-process endpoint.

The problem is that WordPress never sent a Link header pointing to where that post-process endpoint actually lives. So REST clients had no standard way to discover it. They had to hardcode or guess the URL which is fragile and goes against REST API principles.

The ticket had been open since WordPress 5.3. Zero pull requests. Four years untouched.

Reading the code before writing anything

Before writing a single line I cloned WordPress develop:

git clone https://github.com/WordPress/wordpress-develop.git
cd wordpress-develop

Then I opened src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php and searched for X-WP-Upload-Attachment-ID.

Here is what I found. The raw header() call happens very early in create_item() before the $response object even exists. This is intentional. If the server fatals during wp_update_attachment_metadata() the client still gets the attachment ID from that header and can recover.

But the Link header does not need to go out at that same moment. It can be added to $response after the response object is constructed, right next to where the Location header is already being set. No order-of-operations problem at all.

The actual fix

After the Location header I added this:

/*
 * Add a Link header pointing to the post-process endpoint so REST clients
 * can formally discover it and resume image sub-size generation if the
 * initial upload processing fails due to a server error.
 *
 * @since 6.8.0
 */
$response->add_link(
    'https://api.w.org/action-post-process',
    rest_url( sprintf( '%s/%s/%d/post-process', $this->namespace, $this->rest_base, $attachment_id ) ),
    array( 'embeddable' => false )
);

One thing I want to explain here is the relation type. The original ticket suggested using edit-media as the link relation. But edit-media is already used by the /edit endpoint in the same controller. Using it for post-processing would be semantically wrong and would confuse clients that rely on relation types having consistent meaning. The api.w.org/action-* pattern is what core uses for action links so I followed that instead.

Generating the patch file

git diff src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php > 48257.patch

I ran cat 48257.patch to verify only my intended lines changed before uploading anything.

Writing the Trac comment

This is the part most people underestimate. The comment you write on the ticket is evaluated just as seriously as the code itself.

I explained what I understood the bug to be, why the order-of-operations issue is still present in trunk, why my approach works without hitting that issue, why I chose a different relation type than the one suggested, and what feedback I was looking for from core contributors.

That written explanation took me longer than the code change itself. But if you just upload a patch with no context you are making the reviewer do all the work of figuring out your reasoning. Most of the time they won't bother.

What I took away from this

Read the full ticket history including linked tickets before writing anything. The real context is almost always buried in the comments not the description.

Comment on the ticket before writing code. Post your intended approach and ask if it makes sense. This protects you from spending hours going in the wrong direction.

Small focused patches move faster. My patch changes 13 lines in one file. A reviewer can evaluate it in a few minutes.

The writing matters as much as the code. Your comment is a signal about how you think and communicate. For a distributed team that works async this is arguably more important than the code quality itself.

How to find your first ticket

Start here:

https://core.trac.wordpress.org/query?status=new&keywords=~needs-patch&component=REST+API&type=defect+%28bug%29

Sort by modified date descending. Look for tickets with zero pull requests and a clearly reproducible bug. Skip anything with recent "can't reproduce" comments or active disagreement between core committers about the right fix.

Pick something small. Read everything. Comment before you code. Write like you care about the reasoning not just the result.

That is genuinely the whole process.

推荐订阅源

DEV Community