My WordPress Core Contribution Workflow

During an informal meetup between the WordPress Core committers attending WordCamp US 2024, one of the topics we discussed was how each of us was handling commits. Given that WordPress Core uses svn and Trac for its source of truth but git and GitHub are encouraged for contributing, it can be a bit of a hassle to synchronize changes when it comes to committing code to WordPress Core.

Fortunately, this is only relevant for the folks that commit code, i.e. nothing that a new contributor needs to worry about. Yet, there’s a good number of committers, and new ones are added regularly, so we thought it would be good to document our workflows. There’s no “official” documentation about this, simply because there’s no universally recommended approach. Many committers have come up with their own solutions throughout the years, so we decided it would be a great idea if each committer documented their approach, so that we would have a number of solutions to compare and for newer committers to review and choose from.

This brief article outlines my personal workflow for committing to WordPress Core.

Here’s a (non-exhaustive) list of other committers’ posts on the topic that I’m aware of so far:

• Aaron Jorbin’s commit workflow
• Joe McGill’s commit workflow

Managing the git and svn checkouts in the same directory

Before I outline my workflow, I need to give credit to my friend and colleague Weston Ruter. He is the one that came up with more or less the entire solution that I’m using and describing in this post, and it’s been working seamlessly for me for many years now.

I find it tedious to synchronize changes from the git checkout of WordPress with the svn checkout of WordPress in another location. So what’s the solution for that? Manage the two in the same directory so that synchronization happens automatically! There are definitely some quirks to figure out when using the same directory, but fortunately Weston has already done all of that. He created a Bash script called git-svn-up that handles the synchronization in a single command.

To refresh my local checkouts from both VCS sources, I simply run:

git svn-upCode language: Bash (bash)

I can also easily checkout a specific branch from both VCS sources, for example:

git svn-up 5.0Code language: Bash (bash)

Having both checkouts in the same place makes it trivial to checkout the code from a GitHub pull request and then having it readily available to commit to WordPress Core SVN. Once I tried this approach Weston shared with me, it was a game changer in ease of use. Honestly, at this point I don’t mind it at all anymore that WordPress Core uses SVN. It doesn’t get in the way anymore when using this approach.

Let’s look at how we can set up our environment to use this workflow.

Initial setup

Setting up the command

You can download the Bash script from this repository. You could put it into a directory in your $PATH as an executable file git-svn-up. That way, you can easily call it from anywhere.

If you like, you could additionally create a git alias for it. That’s really just a nice to have, but I find it convenient to call it as if it was a subcommand of git, i.e. git svn-up. To do so, you need to edit your ~/.gitconfig file to configure an alias, e.g. something like this:

[alias]
	svn-up = "!$DIR_WHERE_YOU_PUT_THE_FILE/git-svn-up $1"Code language: JavaScript (javascript)

That’s all for setting up the command.

Setting up the development checkout

To use the command, check out the git and svn repositories of WordPress into the same directory. For example:

git clone git@github.com:WordPress/wordpress-develop.git wordpress-develop
svn co https://develop.svn.wordpress.org/trunk/ wordpress-developCode language: Bash (bash)

Now, you can use that directory containing both checkouts to contribute to WordPress Core.

A good idea might be to already add your own WordPress Core GitHub fork as a remote, since pull requests for WordPress Core should always come from a fork. For example:

git remote add felixarntz git@github.com:felixarntz/wordpress-develop.gitCode language: Bash (bash)

You can also add a safeguard so that you don’t accidentally push code to the actual WordPress Core repository. This is discouraged anyway, and pull requests in that repository will be automatically closed. You can run this command to ensure that even if you forget to specify a destination when using git push, it will still go to your fork:

git remote set-url --push origin git@github.com:felixarntz/wordpress-develop.gitCode language: Bash (bash)

So now let’s take a brief look at how I use this setup.

Workflow

Whenever I start working on a code change, I refresh my local checkout via git svn-up. Then, I either create a new branch (if I intend to start writing a patch myself) or check out someone else’s pull request (if I intend to locally review, test, iterate on, or commit their patch).

Working on my own patches

Working on my own patches and pull requests is straightforward. I simply create or move to the relevant branch, for example:

git checkout -b fix/12345-ticket-bugCode language: Bash (bash)

Once I have something that’s ready to push, I push it to my own fork via:

git push felixarntzCode language: Bash (bash)

Working on someone else’s patches

Usually as a committer, you review, test, or eventually commit someone else’s code. In those cases, my own workflow begins by checking out the code from the other contributor’s pull request. Let’s say for example that I want to review a pull request from Weston Ruter, in a branch called fix/weston-test on his own fork. His WordPress fork lives at https://github.com/westonruter/wordpress-develop. So I can check out that code by adding his fork as a remote, fetching its code, and then moving to the relevant branch:

git remote add westonruter git@github.com:westonruter/wordpress-develop.git
git fetch westonruter
git checkout fix/weston-testCode language: Bash (bash)

Once I have reviewed the code changes, I could either provide feedback on the pull request, or iterate on the pull request myself, or commit it to WordPress Core.

To iterate yourself, you would simply modify the code, and once you’re ready to push it, you’d push it back to the contributor’s fork – in my example:

git push westonruterCode language: Bash (bash)

To commit the code from the git branch to WordPress Core, thanks to the Bash script I don’t have to synchronize or copy the code somewhere else. I can simply remain in the same directory.

A basic sanity check I usually do is to make sure that the code changes recognized by SVN align with the code changes on the GitHub pull request by using:

git status
svn stat

The git status call shouldn’t show any changes since you’re probably in the latest checkout of the pull request branch. But on SVN you should see those changes since of course they haven’t been added to WordPress Core just yet.

Once you’re confident about the change to commit it, all that’s left to do is to write a commit message and:

svn ci

And that wraps up this post about my workflow.

Questions?

If anything in my explanations is unclear or you have additional suggestions, please let me know in the comments.

If you’re a WordPress Core committer too, I’d love to see you write a post on your workflow as well, as all of us are curious to see how each other is doing it.