ThisCalculator

Everyday

How to Contribute Your First Patch to WordPress Core

Updated · Standard formula, shown below

Contributing your first patch to WordPress core is a rewarding way to give back to the open-source project that powers over 40% of the web. This guide walks you through the entire process—from setting up a local development environment to submitting a patch that gets reviewed and potentially merged. You don’t need to be a senior developer; a basic understanding of PHP, JavaScript, and using the command line is enough to get started.

What You’ll Need

  • A local development environment with PHP 7.4 or later, MySQL or MariaDB, and a web server (Apache or Nginx). Tools like Local, XAMPP, or MAMP work well.
  • Command-line access (Terminal on macOS/Linux, Command Prompt or PowerShell on Windows).
  • Git installed on your computer.
  • A free WordPress.org account (used for the Trac system and the Slack community).
  • Basic knowledge of PHP and WordPress coding standards (the WordPress Coding Standards).

Step-by-Step

  1. Set up a local WordPress installation. Install WordPress using your preferred local environment. You can download the latest version from wordpress.org or use a tool like Local to create a site. Ensure the site runs correctly by visiting it in your browser.
  2. Install the development version of WordPress. Instead of using the stable release, you need the latest development build. In your local site’s directory, replace the WordPress files with the latest from the official repository. The easiest way is to use Git: navigate to your site’s root folder and run git clone https://github.com/WordPress/wordpress-develop.git . (note the dot at the end) or download the source from wordpress.org/download/source/ and extract it, overwriting the existing files.
  3. Set up a local database. Create a new database and user for your development site. Update the wp-config.php file with those credentials. Run the WordPress installation script by visiting your site’s URL in a browser. For development, it’s helpful to enable WP_DEBUG and WP_DEBUG_LOG in wp-config.php to see errors.
  4. Create a fork of the WordPress repository. Go to the wordpress-develop repository on GitHub and click the “Fork” button. This creates a copy under your GitHub account.
  5. Clone your fork locally. In your terminal, navigate to a directory where you want to keep the code (not the same as your local site, but you can use a separate folder). Run git clone https://github.com/your-username/wordpress-develop.git. Then, add the original repository as an upstream remote: git remote add upstream https://github.com/WordPress/wordpress-develop.git.
  6. Find a ticket to work on. Browse the WordPress core Trac system at core.trac.wordpress.org. Look for tickets with the “good-first-bug” keyword or those marked as “needs-patch” that align with your skills. Read the ticket description and any comments to understand the issue.
  7. Create a new branch. In your local clone, create a branch for your work: git checkout -b fix/12345-short-description (replace 12345 with the ticket number and a short description). This keeps your changes isolated.
  8. Write your patch. Make the necessary code changes in your local clone. Follow the WordPress Coding Standards (see the official handbook). Test your changes thoroughly—both the specific bug fix and that you haven’t broken anything else.
  9. Run the test suite (if applicable). WordPress has a PHPUnit test suite. If your change affects PHP, run the related tests to ensure they pass. Instructions are in the tests directory of the repository.
  10. Commit your changes. Stage the files you changed: git add ., then commit with a descriptive message: git commit -m "Fix issue #12345: Short description of the change".
  11. Push your branch to your fork. Run git push origin fix/12345-short-description.
  12. Create a pull request (PR) on GitHub. Go to your fork on GitHub, select your branch, and click “New pull request”. In the PR description, mention the Trac ticket number (e.g., “Fixes #12345”) and provide a clear summary of your changes. The WordPress core team monitors these PRs.
  13. Generate a patch file for Trac. The official way to submit a patch is via Trac. In your terminal, generate a unified diff: git diff upstream/trunk > /path/to/12345.patch (make sure you’re on your branch). This creates a .patch file.
  14. Upload the patch to Trac. Go to the original ticket on Trac, scroll to the bottom, and use the “Attach file” form to upload your .patch file. Add a comment explaining what the patch does and that you’ve tested it.
  15. Mark the ticket as having a patch. In the ticket’s properties, change the “Keywords” to include “has-patch” (if not already there). This signals to reviewers that a patch is ready for review.

Common Mistakes

  • Not using a fork and branch. Directly committing to the main repository is not possible; always work on a branch in your fork.
  • Ignoring coding standards. WordPress has strict coding standards. Use the provided PHPCS ruleset to check your code. A patch that doesn’t follow standards will likely be rejected.
  • Not testing thoroughly. Only test the happy path. Also test edge cases, mobile responsiveness, and compatibility with different themes/plugins.
  • Submitting a patch without a ticket. Every patch must be associated with a Trac ticket. If you find a bug, create a ticket first (if none exists) before working on a fix.
  • Not updating the patch after feedback. Reviewers may request changes. If you don’t update your patch, it will be ignored.

Tips

  • Start small. Pick a ticket that is clearly scoped and labeled as a good first bug. This increases your chance of success.
  • Join the WordPress Slack. The #core channel is where contributors discuss development. Introduce yourself and ask for guidance if needed.
  • Use the WordPress Coding Standards tools. Install PHP_CodeSniffer and the WordPress standards to automatically check your code.
  • Keep your fork up to date. Regularly sync your fork with the upstream repository to avoid merge conflicts: git fetch upstream && git merge upstream/trunk.
  • Be patient and responsive. Core development moves slowly. Respond quickly to feedback and be willing to revise your patch.

Troubleshooting

  • Patch doesn’t apply cleanly. If the patch fails to apply, it’s likely because the codebase has changed. Rebase your branch onto the latest trunk: git fetch upstream && git rebase upstream/trunk, then regenerate the patch.
  • Local site shows errors after setup. Check the wp-content/debug.log file for PHP errors. Ensure your database credentials are correct and that you’ve enabled WP_DEBUG.
  • Git clone fails. If you get permission errors, ensure you have the correct permissions on the directory. On Windows, you may need to run the command as Administrator.
  • Pull request is ignored. The core team primarily uses Trac. Make sure you upload the patch to Trac as well, and mention the PR in the ticket.
  • Tests fail. If PHPUnit tests fail, run them with --filter to isolate the failing test. Check if the failure is due to your changes or an existing issue.

Frequently Asked Questions

Do I need to be a professional developer to contribute?

No. Many contributions come from hobbyists and students. Start with simple fixes like documentation, typo corrections, or small bug fixes.

How long does it take for my patch to be reviewed?

It varies. Some patches are reviewed within days, others take months. The core team is volunteer-based and prioritizes critical issues. Be patient.

Can I contribute to WordPress core without using Git?

Yes, you can manually edit files and create a patch using a diff tool, but Git is the standard and makes collaboration much easier.

What if my patch is not accepted?

That’s okay. Reviewers often provide feedback. Revise your patch and resubmit. Many accepted patches went through several iterations.

Is there a way to test my patch on a live site?

You can use a staging site or a local environment. For more advanced testing, you can use the WordPress Playground, which runs WordPress in the browser.

Do I need to sign a contributor license agreement?

No, WordPress uses the GPL license. By submitting a patch, you agree to license your contribution under GPL v2 or later.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.