Contributing With Git

A large number of contributors strongly prefer working with Git. Since Meta projects are stored in Subversion and mirrored to Git, you can use either one to contribute.

The following workflow uses ticket #986 and the WordPress.tv theme as an example, but the same steps can be applied to anything in the Meta repository.

If you get stuck with anything, you can find lots of information by searching the Web, and if that fails, you can always ask for help in the #meta channel on Slack.

Initial setup Initial setup

The Meta Environment will automatically provision many of the Meta sites for you, and uses Git whenever possible.

If you’d prefer, though, you can also manually setup individual sites or plugins/themes into your existing development environment. To do that, first you’ll need to setup a new WordPress installation the way that you normally would inside your local development environment. Once that’s done, we’ll clone the entire Meta repository, and replace the default wp-content folder with WordPress.tv’s content folder.

git clone git://meta.git.wordpress.org/ /srv/www/wordpress-meta
git -C /srv/www/wordpress-meta config diff.noprefix true

cd /srv/www/wordpress.tv/public_html
rm -rf wp-content
ln -rs "/srv/www/wordpress-meta/wordpress.tv/public_html/wp-content/" wp-content

Top ↑

Starting to work a new ticket Starting to work a new ticket

Before you start on a new ticket, make sure you’re working with the latest code by calling git pull on the master branch. Then, start your work on a new branch and commit your changes to that branch.

It’s important to keep the master branch clean, and only make changes on a separate branch. You should keep separate branches for each ticket you work on.

cd wp-content
git checkout master
git pull
git checkout -b 986

Now you can make your changes. When you’re done, commit them:

git commit

Top ↑

Continuing previous work on a ticket after some time has passed Continuing previous work on a ticket after some time has passed

If you’re working on a non-trivial change, it may take several days or weeks to finish. Just make sure you keep the master branch updated, and frequently merge it into your working branch, so that you’re always working with the latest code.

Start by committing any changes you’ve made to your branch, then update master and merge it into your branch.

git commit

git checkout master
git pull

git checkout 986
git merge master

Now you can make your changes. When you’re done, commit them:

git commit

Top ↑

Generating a patch Generating a patch

The Meta team uses Trac to manage issues rather than a Git-aware platform like GitHub, so instead of sending pull requests, you’ll upload a patch to Trac.

When you’ve committed all your changes and you’re ready to submit your work, update the master branch one last time, and merge any changes to your branch. Then, generate a diff with the –no-ext-diff option, to avoid any conflicts with external diff clients.

git checkout master
git pull

git checkout 986
git merge master
git diff --no-ext-diff master > 986.diff

Now that you’ve created 986.diff, you can upload it to the ticket on Meta trac.

Top ↑

Applying patches Applying patches

Sometimes you’re collaborating with other contributors, and you want to build off of work that they’ve done. If they’ve uploaded a patch to Trac, you can apply it to your local copy with the patch command.

patch comes bundled with OS X and most Linux distributions, and is available for Windows as part of Cygwin.

You’ll want to use a fresh branch, because the patch will contain all of the changes against the original code; if you tried to apply it to a branch that you had an earlier version of the patch, you would have to resolve merge conflicts.

It’s best to start in whatever directory the patch was created in, so that the file paths line up. To determine where the file was created, you can examine the paths in the file. If the paths don’t match up, patch will prompt you to enter the path to the file that should be patched.

git checkout master
git pull

git checkout -b 986.2
patch -p0 < 986.2.diff