How to Submit Your First WordPress Core Patch: A Technical Guide

How I Submitted My First WordPress Core Patch (And What I Learned)

Kunal Pareek submitted his first WordPress core patch by targeting ticket #48257, a bug open since WordPress 5.3. The fix addresses a REST API discoverability problem in the media upload endpoint where the server failed to send a Link header for post-processing.

Why This Matters

In theory, contributing to major open-source projects requires decades of experience, but reality shows that many tickets remain open due to a lack of clear documentation or consensus rather than technical complexity. This specific case highlights how a four-year-old defect persisted because it lacked a standard way for REST clients to discover retry endpoints, requiring a manual implementation of WordPress-specific action links.

Key Insights

• WordPress Ticket #48257, 2019: A REST API defect remained unpatched for four years despite a clear reproducibility path.
• Trac filtering for ‘needs-patch’ used by Kunal Pareek: Selecting tickets with specific keywords prevents time loss on non-actionable bugs.
• Semantic link relations in WordPress Core: Using api.w.org/action-* instead of edit-media ensures consistent API discoverability.
• Small-scale patching (13 lines): Core reviewers prioritize focused changes that minimize regression risks in class-wp-rest-attachments-controller.php.
• Technical async communication on Trac: The written justification for a patch is as critical as the code quality for distributed teams.

Working Examples

Cloning the WordPress development repository.

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

Adding the Link header to the REST API response object.

$response->add_link(\n'https://api.w.org/action-post-process',\nrest_url( sprintf( '%s/%s/%d/post-process', $this->namespace, $this->rest_base, $attachment_id ) ),\narray( 'embeddable' => false )\n);

Generating the patch file for submission.

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

Practical Applications

• WordPress REST API clients identifying post-process endpoints via Link headers. Pitfall: Reusing the edit-media relation type causes semantic collisions with standard edit endpoints.
• Open source contributors using Trac queries to find ‘needs-patch’ tickets. Pitfall: Working on tickets without recent reproduction confirmation leads to dead-end development.

References:

• https://dev.to/kunal_pareek/how-i-submitted-my-first-wordpress-core-patch-and-what-i-learned-a72