Learning how to make your first code contribution can be intimidating, but it’s not as hard as you may think.
This tutorial will walk you through the minimal steps necessary to fix a sample bug. Once you’ve gone through it, you can apply the same steps to real bugs and feature requests. It will take between 10 minutes and a couple of hours, depending on your development environment, prior knowledge, etc.
If you get stuck anywhere along the way, feel free to ask for help in the #meta
channel on Slack.
Find a Bug to Fix
The MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team uses a tool called Trac to manage bug reports and feature requests. A new ticket is opened when someone reports an issue and then closed when the issue is resolved.
Normally you’d look for a ticket to work on by browsing the reports, but for this tutorial, we’ll be using ticket #1885.
If you open that ticket, you’ll find that it has a description of the “bug” that we’re going to fix. The change is intentionally minimal since the important thing right now is just learning the process.
Setup Your Development Environment
Now that you know what bug to fix, you’ll need a development environment to work in.
If you don’t already have an environment, individual projects will often have one available. For example, the Pattern Directory repository has instructions for setting up a Docker environment. If your project doesn’t have an environment, you can try the WordPress Meta Environment.
If you do already have an existing development environment:
- Open a terminal and copy/paste the commands in the following steps. If any command contains a path to a directory, you’ll need to modify it to match the actual path on your computer.
cd /path/to/your/wp-content
git clone git://meta.git.wordpress.org/ wordpress-meta
- Don’t have GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/.? You can download it from git-scm.com.
cd plugins
- Create a symlink to the WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They’re one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Fonts pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party:
- OS X/Linux:
ln -s ../wordpress-meta/wordcamp.org/public_html/wp-content/plugins/wc-fonts/ wc-fonts
- Windows:
mklink C:\Users\jane\Desktop\sites\example.org\wp-content\plugins\wc-fonts C:\Users\jane\Desktop\sites\example.org\wp-content\wordpress-meta\wordcamp.org\public_html\wp-content\plugins\wc-fonts
- OS X/Linux:
- Browse to wp-admin/plugins.php and activate the WordCamp Fonts plugins.
Regardless of which environment you use, the final step is to browse to the Appearance > Fonts
screen. You’ll see that the screen’s headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. is “Fonts”; in the next section we’ll change it to “WordCamp Fonts”.
Fix the Bug
Now that you have a development environment setup, you can go ahead and fix the bug.
- In a terminal, run the following commands:
cd /path/to/your/wp-content/plugins/wc-fonts
- If you’re using the Meta Environment, it’ll be
{path-to-your-copy}/www/wordpress-meta-environment/meta-environment/wordcamp.dev/public_html/wp-content/plugins/wc-fonts/
- For example,
cd /Users/jane/vhosts/vvv-wme/www/wordpress-meta-environment/wordcamp.dev/public_html/wp-content/plugins/wc-fonts
- If you’re using the Meta Environment, it’ll be
git checkout -b 1885
- Open your preferred IDE or text editor, then open the
wp-content/plugins/wc-fonts/wc-fonts.php
. Search for therender_admin_page
function. - Change the header line.
- Back in the terminal, make sure you’re still in the
wc-fonts
directory, and then run:git diff
- The results should look similar to the screenshot below.
git add wc-fonts.php
git commit
- A file editor will appear so that you can write the commit message. Enter something like,
Change screen headline from 'Fonts' to 'WordCamp Fonts'
, then save the file and exit the editor.
Share Your New Code
Now that you’ve fixed the bug, we want to share the new code with the Meta team, so that they can incorporate it into the official code repository. If the tasks you work on are supported by 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 be the repository owner. https://github.com/, you can simply submit a pull request (PR) to contribute your changes. Otherwise, the first step would be generate a patch file, which contains the changes in a format that can be easily applied to other computers.
- In a terminal, run:
git diff master > 1885.diff
- If someone else has already uploaded a file named
1885.diff
, then name yours1885.1.diff
,1885.2.diff
, etc. - If running
git diff
opens a GUI program, then try it again with the--no-ext-diff
parameter; e.g.,git diff --no-ext-diff master > 1885.diff
- If someone else has already uploaded a file named
- Open the ticket in your browser.
- If you’re not logged in to TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., log in.
- If you don’t have a WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ account, create one.
- Click the Attach File button in the Attachments section, and upload your patch file.
- If you don’t see the button, use the links in the previous to log in or create an account.
- Leave a comment on the ticket indicating that you’ve uploaded a patch. Trac doesn’t send notifications when files are uploaded, so people will only notice your patch if you leave a comment about it.
Conclusion
You’re done! You now have all of the basic knowledge you’ll need to contribute code. There’s a lot more to learn, of course, but you can pick up the rest along the way.
To get started on a new contribution, just find another ticket to work on and follow the same steps as above. The good-first-bugs report on Trac is a great place to start.
If you need help, you can ask in the #meta
channel on Slack.