Learn How to Contribute Code

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 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 Find a Bug to Fix

The Meta 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.

Top ↑

Setup Your Development Environment 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 an environment, install the WordPress Meta Environment. It will automatically provision an environment for you.

If you do already have an existing development environment:

  1. 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.
    1. Not sure how to open a terminal? Check out these instructions for OS X or for Windows.
  2. cd /path/to/your/wp-content
  3. git clone git://meta.git.wordpress.org/ wordpress-meta
    1. Don’t have Git? You can download it from git-scm.com.
  4. cd plugins
  5. Create a symlink to the WordCamp Fonts plugin:
    1. OS X/Linux: ln -s ../wordpress-meta/wordcamp.org/public_html/wp-content/plugins/wc-fonts/ wc-fonts
    2. 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
  6. Browse to wp-admin/plugins.php and activate the WordCamp Fonts plugins.

setup-dev-environment

Regardless of which environment you use, the final step is to browse to the Appearance > Fonts screen. You’ll see that the screen’s header is “Fonts”; in the next section we’ll change it to “WordCamp Fonts”.

 

Top ↑

Fix the Bug Fix the Bug

Now that you have a development environment setup, you can go ahead and fix the bug.

  1. In a terminal, run the following commands:
    1. cd /path/to/your/wp-content/plugins/wc-fonts
      1. 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/
      2. For example, cd /Users/jane/vhosts/vvv-wme/www/wordpress-meta-environment/wordcamp.dev/public_html/wp-content/plugins/wc-fonts
    2. git checkout -b 1885
  2. Open your preferred IDE or text-editor, then open the  wp-content/plugins/wc-fonts/wc-fonts.php. Search for the render_admin_page function.
  3. Change the header line so that instead of <h1><?php esc_html_e( 'Fonts', 'wordcamporg' ); ?></h1>, it says <h1><?php esc_html_e( 'WordCamp Fonts', 'wordcamporg' ); ?></h1>
  4. Back in the terminal, make sure you’re still in the wc-fonts directory, and then run:
    1. git diff
      1. The results should look similar to the screenshot below.
    2. git add wc-fonts.php
    3. git commit
    4. 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.

fix-the-bug

Top ↑

Share Your New Code 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. The first step in that process is to generate a patch file, which contains the changes in a format that can be easily applied to other computers.

  1. In a terminal, run: git diff master > 1885.diff
    1. If someone else has already uploaded a file named 1885.diff, then name yours 1885.1.diff, 1885.2.diff, etc.
    2. 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
  2. Open the ticket in your browser.
    1. If you’re not logged in to Trac, log in.
    2. If you don’t have a WordPress.org account, create one.
  3. Click the Attach File button in the Attachments section, and upload your patch file.
    1. If you don’t see the button, use the links in the previous to log in or create an account.
  4. 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.

share-your-code

Top ↑

Conclusion 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.

 

Top ↑

More Resources More Resources