Grunt is a JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com-based task runner that WordPress uses to automate development tasks. This guide assumes you have already set up a local testing environment.
Why use Grunt?
- To apply patches from TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets easily.
- To build the WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. files after changes.
- To run automated tests.
Applying Patches
Prefer a video walkthrough?
Follow along with this step-by-step setup guide as you work through the instructions below.
The most common task for testers is applying a patch from a Trac ticket to your local environment.
1. Find the Ticket or Patch ID
Go to Needs Patch Testing in Core Trac and find the ticket you want to test.
- Ideally, identify the Ticket ID (e.g.,
27307). - Or, find the specific Patch URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org (e.g., `https://core.trac.wordpress.org/attachment/ticket/27307/27307.diff`).
2. Apply the Patch
In your terminal, navigate to your wordpress-develop directory and run:
Using the Ticket Number (Recommended):
This will download and apply the latest patch for that ticket.
npm run grunt patch:27307
(Replace 27307 with the actual ticket number)
Using a Specific Patch URL:
npm run grunt patch:https://core.trac.wordpress.org/attachment/ticket/27307/27307.diff
Using a GitHubGitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged by the repository owner. https://github.com/ Pull Request:
You can apply patches directly from a GitHub Pull Request using either the direct URL or the .diff URL.
Option 1: Using the Direct Pull Request URL
npm run grunt patch:https://github.com/WordPress/wordpress-develop/pull/10815
Option 2: Using the Diff URL
npm run grunt patch:https://github.com/WordPress/wordpress-develop/pull/10815.diff
3. Build the Changes
After applying a patch, you may need to build the changes depending on what was modified:
- JavaScript or CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. changes: You MUST run the build command to compile the assets.
npm run build:dev
- PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. https://www.php.net/manual/en/preface.php-only changes: Running the build command is not mandatory, but it is good practice to ensure everything is in sync.
Running Tests
Once a patch is applied, you should run automated tests to ensure no regressions were introduced.
For detailed instructions on running PHPUnit and E2E tests, see Run Automated Tests.
Writing a Test Report
After testing a patch, share your results by writing a test report on the Trac ticket. For report templates and guidelines, see Patch Testing.
Troubleshooting
“Patch failed to apply”
- Cause: The code in your local version might be different from what the patch expects (e.g., your branch is outdated).
- Fix: Update your repository to the latest trunk before applying the patch:
git checkout trunk
git pull upstream trunk
If you get an error about upstream not being found, add it first:
git remote add upstream https://github.com/WordPress/wordpress-develop.git
“Cannot find module ‘grunt-cli/bin/grunt’”
- Cause: Missing dependencies.
- Fix: Reinstall dependencies:
rm -rf node_modules
npm install
Reverting Changes
To remove a patch and go back to a clean state:
git checkout .
git clean -fd
