My WordPress Contribution Workflow

Yesterday at WordCamp US there was a gathering of folks who have commit access to WordPress and a request to share how everyone performs their work¹. This post is me sharing my current typical setup.

Working with code

For all development I work in the git mirror, wordpress/wordpress-develop. It’s normal for me to have more than 80 active branches. Currently I have 103. Tools, GUIs, and helpers for git usually confuse me because I don’t know everything they are doing. I stick to the command line for everything except the occasional use of Kaleidoscope for a visual diff. There are seven remotes in my local repo.

Almost everything I end up proposing to Core comes months after prototyping and throwing away previous drafts. I often have two or three branches for my work and those branches represent different attempts or approaches² to a given problem. Sometimes work stalls on one approach and I pick it up months or years later³. It’s also frequently the case that I’m working on something in parallel with someone else. Because of this, I rely on tools like git range-diff as well as git rebase -i --rebase-merges --keep-base trunk to help me understand how changesets evolve and fit together. I love git and am constantly impressed with how much it’s able to help me in complicated workflows.

Committing to Core

When it comes time to commit, I have a checkout of the develop.wordpress.org subversion (svn) repository. I keep it updated with svn up and svn revert -R .. It’s only there for commits, never for development. Thanks to some advice I got from another contributor, I keep a commit.msg file in that directory where I prepare the commit statement.

git fetch upstream && git merge upstream/trunk && git push

For all of my commits, whether my own work or when I’m committing on behalf of someone else, I merge trunk into the branch and push the updates to GitHub to ensure that all of the continuous integration (CI) checks complete successfully. This is inconvenient, as it introduces something like a twenty minute delay, but I prefer having passing tests even when I know that the change with trunk‘s updated couldn’t break anything new. Another reason I merge in trunk is that I like having a true record of exactly what code was committed. I don’t want the version of the svn repository to differ in any way from the commit in the PR.

git diff upstream/trunk | pbcopy
cd ../wp-svn/trunk
pbpaste | patch -p1

With the commit file prepped, I create a patch from the git branch and send it to my copy buffer. I never create helper scripts to automate these steps because I find that doing them manually helps me learn and remember how the systems work and how they work differently from each other. In this case, I have to remember to svn add any new files, because svn only automatically queues the changed files for the commit.

I run svn status and svn diff to review the changes, ensuring it’s exactly what I expected, and then bat commit.msg⁴ to review the commit message.

svn commit --file commit.msg

Once the commit succeeds I go back to the Pull Request and leave a comment to close it out. The comment gets a link to the changeset in Trac as well as the commit in the git mirror. It’s important to me that people are able to follow working URLs from either repository, whether they are viewing the change in Trac, or on the command line in git, or on Github. This is also why I add working URLs inside the commit message.

1. See Aaron Jorbin’s post and Joe McGill’s post. ↩︎
2. The HTML Processor was first developed locally on a branch that was never pushed, then a second version shared in #6, and finally a third iteration in #4519. ↩︎
3. Sourcing block attributes on the server was explored in #46345 but it wasn’t ready. It informed further work on the HTML API but went on hold. It was restarted after new developments in Core in #6388, but has been stalled again. At some point, I will pick up development where I left off, or start a new branch with a brand new approach. ↩︎
4. In place of cat I have long used bat (or batcat) instead because of the features it provides. These include syntax highlighting by default, and automatic paging for content larger than one shell screen. ↩︎