Hey, you! Want to contribute to Jetpack?
Yeah, you: did you know that you could be instrumental in making Jetpack more robust and secure? If you use and love Jetpack, why not contribute to the project?
(If you don’t use and love Jetpack, what are you waiting for? Download it now!)
Like WordPress itself, Jetpack is open-source. You can test planned improvements, check out the code, file and view bug reports, and even submit your own patches. The community’s contributions are what make WordPress and Jetpack so strong.
By contributing to Jetpack, you improve the functionality of millions of sites while gaining hands-on development experience. Best of all, developers of all levels can help — whether you can barely recognize a filter (or don’t know what that means) or you’ve already authored your own plugins, there are ways for you to pitch in. Blast off:
- Beginner, intermediate, and advanced contribution options.
- How to check out the source code.
- How to create a great bug report.
- How to write and submit a patch.
- Best practices for WordPress development.
- More resources.
Backyard Rockets: Jetpack Newbies
Just getting to know what Jetpack is? Welcome!
Next, how about signing for beta testing? Beta testers give updates, fixes, and new modules a test run before they’re publicly released, so they’re an important part of the development process. If you’re interested in joining the beta group, fill out this form to let us know.
Once you have a handle on how Jetpack works, why not take a look at Trac, our issue-tracking tool? You’ll be ready to start submitting bug reports in no time.
Long-Range Flight: Intermediate Coders
If you’re comfortable reading and editing code but aren’t yet writing your own from scratch, help the bug zappers by submitting bug reports. If you’ve never submitted a bug report before, check out Creating a Great Bug Report to make sure your reports have all the info a developer needs to resolve the issue quickly and effectively.
If you’re going to be submitting reports, you’ll also want to get familiar with Trac. Once you get comfortable reporting, start looking around the code and get ready to take the next step — submitting patches.
Intergalactic Travel: Advanced Developers
Do you write your own code? Maybe you’ve written your own plugin, or have put on sunglasses to peer directly into the core of WordPress. Are you comfortable reading other people’s code and suggesting improvements?
If this is you, jump into the fray and start creating and submitting patches. Take a look at these outstanding issues to get an idea of the types of things the community has identified as needing attention.
The Nuts and Bolts of Contributing
Joining the Beta Group
Our beta group is a group of smart people (a select group of WordPress users and developers) who tell us what we’re doing wrong (and right) in the next version of Jetpack. Your mission as a beta tester is to help us test the next version of Jetpack and let us know about your experience. Is the UI confusing? Is a module not working properly?
Contact us to let us know if you’re interested in helping out. To participate, you’ll need to download and install the Jetpack Beta Tester plugin, and be sure you’re running the latest version of WordPress. (Note: you won’t be able to access the Beta Tester plugin until you’ve been added to the group.)
Most software projects, including WordPress, use a version-control system to keep track of source code and revisions. WordPress and Jetpack use their own installations of Subversion for version control. Here are the basics of connecting to our Subversion repository.
(If you’re not familiar with Subversion, the teaching tools at OpenHatch Training Missions are a great place to start.)
The easiest way to get Subversion is to download a binary package for your operating system from Subversion’s web site – there are packages for most major operating systems, including Mac OSX, Windows, several versions of Linux, and more. You can also build Subversion directly from source code. From the Subversion web site, download the latest source code release. After unpacking it, follow the instructions in the
INSTALL file to build it.
The source code and revisions are kept in a repository. You connect to the repository using either the command line interface (CLI) or with a client program, which lets you check out, view, edit, and patch the source code. For Windows, the recommended SVN client is TortiseSVN (free and open source) and for Mac, Cornerstone (paid).
The Jetpack repository is available here, and has three important sections:
- Trunk: The latest development code.
- Tags: Codes that let you know what version of Jetpack you’re looking at (e.g., 2.3.1). All publicly-released versions of Jetpack have a tag.
- Branches: Previous Jetpack releases. Sometimes when there are major new Jetpack releases, we maintain the previous release with bug fixes (usually limited to major bugs and security issues).
You can view all the files in the repository with the list command:
svn list http://plugins.svn.wordpress.org/jetpack/trunk/
Checking Out the Code
Once you install Subversion, you’ll need to check out the code before you can work on it — that is, you’ll download the code from the repository to your computer. Here’s how:
- Make an empty directory for your copy of the code
- Change to that directory
- Execute the checkout command on the trunk, branch, or tag you are interested in. For instance, to check out thetrunk (latest development version):
svn co http://plugins.svn.wordpress.org/jetpack/trunk/
If it’s been a while since you checked out the code and you want to make sure you’re using the latest version, use the update command (make sure you first change to the original directory you used):
If you already have a working copy of the trunk but want to switch to the code from a prior release, use the ‘svn switch’ command to update all the files in your working copy. For example, this command switches to version 2.0:
svn switch http://plugins.svn.wordpress.org/jetpack/tags/2.0/
Trac is a ticket database used to track projects and bugs — we use it to manage new features, bug reports, and general project tasks. It’s designed to make it as simple as possible for people to report bugs and submit patches to the code. (NB: this Trac is specifically for WordPress plugins — WordPress Core has its own Trac, with separate instructions.)
You can see all the current open bug reports and enhancement requests for Jetpack right here.
The Anatomy of a Trac Ticket
A Trac ticket contains these fields:
- Reporter — the ticket author (that is, you).
- Type — the kind of ticket, like a feature request or a bug.
- Component — the project module the ticket refers to (e.g., Photon, Publicize) .
- Version — the Jetpack version the ticket refers to (e.g., 2.3.1, 2.3.2).
- Keywords — a list of keywords based on the subject of the ticket, to help searchers.
- Priority — the importance of the issue, ranging from trivial to blocker.
- Milestone — the deadline for resolving the issue.
- Assigned to/Owner — they key person responsible for the ticket (possibly also you).
- Cc — a comma-separated list of other users or to notify.
- Resolution — the reason the ticket was closed — either fixed, invalid, wontfix, duplicate, or worksforme.
- Status — the ticket’s current status — either new, assigned, closed, or reopened.
- Summary — a brief summary of the issue.
- Description — a specific, descriptive, clear and concise explanation of the bug or issue.
In addition to reporting bugs and submitting patches, you can also follow the progress of any Trac ticket you’re interested in or add details to an existing ticket.
To follow a ticket, log in to Trac, find the ticket, scroll to the bottom, click on Modify Ticket, and select the checkbox next to your email address:
If you have information to add to an existing ticket, add a comment to it by clicking Add Comment to pull up a text box.
Once you’ve checked the Add to Cc: box and/or added a comment, you’ll notice that whatever changes you’ve made will show up in a Preview box at the bottom of the page. Once you’re satisfied, click Submit Changes.
Now, let’s use Trac to submit a new ticket.
Three Steps to Being a Trac Star
1. Make sure the bug is really a bug.
Before you report a bug, make sure it’s not just internet gremlins or a compatibility problem. Before you begin your investigation, make sure you’re running the latest versions of WordPress and Jetpack.
Start by turning off all your other plugins and switching to the default TwentyEleven or TwentyTwelve themes. Do you still see the issue? If so, you might have found a bug.
If the issue disappears, it was probably caused by a conflict with one of your plugins or themes. Now, test them one at a time — activate only Jetpack and that theme or plugin to eliminate other variables. When the issue reappears, you’ve found the culprit!
2. See if it’s already been reported.
To check if a bug has already been reported, you can:
- Check out the Known Issues page.
- Look through the current list of Trac tickets.
- Browse the Jetpack Support Forum.
Not mentioned in any of those places? Not caused by a conflict with another plugin or theme? By George, you’ve found a bug! Time to report it.
3. Submit a detailed, precise ticket.
The more specific your ticket is, the easier it will be for someone to zap the bug. Log in to Trac, open a new Jetpack Trac ticket, and be sure to fill out all the relevant details: a concise summary, a clear description, and whether it’s a defect/bug or an enhancement request. If it’s been mentioned by someone else, like on the Jetpack Support Forum, include a link.
(You don’t have to worry about filling in the keywords or selecting the owner, priority or severity — we’re notified on every ticket, and we’ll add that.)
Here’s a sample of what a helpful summary looks like:
Summary of the issue: The Jetpack Image widget won’t display the selected image.
Steps to reproduce:
- Activate the Extra Sidebar Widgets module
- Include the Jetpack Image widget in the sidebar, and fill out all the fields, including the image URL
- Save the Widget and view your site
Expected behavior or result: The sidebar should display the selected image
Actual behavior or result: An error appears: “Image could not be found.”
Link to Example (if applicable): http://example.com/image-widget/
Screenshots: screenshot of error message goes here
Cross-Browser Testing, AKA “Don’t Forget About Internet Explorer 8″
If you believe you’ve come across a bug and you’ve worked through all the steps detailed above, it’s worth checking to see if the issue can be reproduced in different browsers. You can find download links to the most recent versions of all the major browsers on Browse Happy.
If you’re fixing a bug, edit the files in the directory where you checked out the code. When you’re ready to submit your fixes, create a bug ticket on Trac, and use these commands to see what parts of your working copy are different from the source code in the Jetpack repository:
(Note: You may need to change to a sub-directory (such as trunk) to execute these commands.)
- To get a list of files you’ve changed, use the status command:
- To show the changes you’ve made in a line-by-line patch format (which will also be used in exporting patches), use the diff command to output a unified diff of all the changes you made to the source code:
- To show the differences in a single file, use the diff command (or include multiple file paths to show differences between a set of pages):
svn diff path/to/file
To share the changes you’ve made with others, export them as a .diff or .patch file (both plain text files with the same format — either extension is fine). Once you export your changes, attach the file as a patch to a Trac report. Make sure you generate your patches from the root of Jetpack, rather than a sub-directory.
- Use the diff command with > to indicate the destination file. This saves the diff output for any files changed in your working copy.
svn diff > my-patch-file.diff
- If you have changes in your working copy you don’t want to include, specify the specific file(s) you want the diff to show:
svn diff wp-admin/comment.php wp-includes/comment.php > comments-patch-r3234.diff
- To implement a .diff or .patch file into a working copy use the ‘patch’ command:
patch -p0 < /path/to/patch.diff
- To reset your working copy to the code you checked out (to throw away any changes you’ve made):
svn revert . -R
- You can also do a revert for just a single file:
svn revert path/to/file