Contributing to Twenty Seventeen

Sami Keijonen shares his experience as a first time contributor to the WordPress default theme building process. He primarily worked within the realm of SVG icons for the Twenty Seventeen theme.

Editor’s Note: This is a guest post by Sami Keijonen. Sami is a developer, the owner of the Foxland theme and plugin shop, and hails from Finland.

Every year since 2010, WordPress has shipped with a new default theme, breaking the cycle of Kubrick being the primary default theme for years before that.

In 2010, the default theme was called Twenty Ten. In 2011, the default theme was called Twenty Eleven. You get the idea.

While every default theme has been unique in its own way, Twenty Seventeen was particularly compelling in a way we haven’t seen in a default theme since Twenty Fourteen.

Twenty Fourteen was the first theme that really made people think WordPress could be used for more than “just a blog” on a mass scale. It is a magazine theme.

Twenty Seventeen — released with WordPress 4.7 — is the first theme that really made people think WordPress could be used for more than “just publishing content” on a mass scale. It is a business theme.

Twenty Seventeen WordPress Theme Screenshots

Prior to WordPress 4.7, I contributed by helping out in the support forums and building accessible themes. But I had never contributed to core before.

When I saw the previews, I knew I wanted to contribute, and began to follow development on GitHub to see if there was anything that I could lend my talents to and eventually make my first core contributions.

When I saw Morten Rand-Hendriksen open an issue about replacing icon fonts with SVG icons, I knew I had found the perfect “in” to start contributing to core.

Contributing SVG icons system to Twenty Seventeen

Example image of SVG icon set

I had already switched from icon fonts to SVG icons in my public themes, so this was something I immediately felt confident in contributing to core.

Development started in GitHub, where fellow contributors would create issues and submit pull requests.

Then, everything moved to WordPress SVN, where new patches were submitted.

I’ll summarize what I learned in the process.

What I learned about contributing

I regret not keeping a diary. Not necessarily to keep track of what I contributed, since that’s all documented in the open.

But rather things like my emotional state. My feelings ranged from despair to overwhelming joy throughout my contribution experience.

I learned new things about code and collaborating with others in GitHub and SVN. Again, something not necessarily documented in patches and the like.

Git workflow

I’m not good with Git, and still don’t fully understand how rebasing works. I messed up my commits a couple of times. Not a big deal, but I got different error messages no matter which workflow I tried. I realized that I need to know more about Git, and be more patient.

Eventually I understood enough to get my contributions through the door, but I’m still confused about how to rebase a pull request.

Follow the development through to the end, and beyond

I started out by replacing only the social link icon fonts to SVG icons. Soon, I realized that a step-by-step process was not going to work because of new related commits coming in all the time that potentially conflicted with my code.

It was better to replace all icon fonts, not just the social ones, with SVGs, and then work from there. I was also keeping track of style changes in RTL languages and IE8.

At this point, the work was just getting started.

Once you start contributing, you shouldn’t just disappear with no explanation. If you’re running low on time or have other obligations, it’s totally understandable, but be sure to politely inform others you can’t continue anymore, so they can pick up where you left off.

As the o2 slogan states: “Communication is oxygen.”

Coding standards and automated tests

After several commits and iterations, my first pull request was accepted.

As you can see in my first commits, I didn’t pass the WordPress coding standards. I needed to be more precise and follow the coding standards to the tee. With enough practice, I’m sure it’s possible to write standards-compliant code “naturally” but I was looking for a way to automate the code checks.

I tried to get Atom to evaluate my code on the fly, but I just couldn’t get it to work. Like my Git experience, I got different error messages no matter what I tried.

Eventually, I was able to use PHPCS via the command line, and fixed any issues discovered manually. But it would’ve been nice to have those checks automated.

Working with batches in SVN

Once the development moved to SVN, I began to get a little worried. As I described earlier, not too long ago, I was struggling just to use Git. However, thanks to the following tutorials I quickly got up to speed.

Turns out, it wasn’t much to be worried about. Although I didn’t quite understand the concept of branches and tags in my local environments, and jumping between them like I know how to do with Git.

Anyway, I eventually got my first props with the help of others.

Technical overview of the SVG icons system

I adapted this contribution from the code and concepts first presented by others.

  1. WebDevStudios has their own starter theme called wd_s. I really like how they set up SVG icons and we fine-tuned them in Twenty Seventeen. Perhaps they will integrate those improvements back into their own project. Again, open source rocks.
  2. Justin Tadlock invented the social links menu concept. I just took that concept and applied it to SVG icons rather than icon fonts.

All the main SVG-related functions can be found in the inc/icon-functions.php file. It’s well-documented in the code, but here’s a summary:

  • Include the SVG sprite file via the wp_footer hook.
  • twentyseventeen_get_svg() function returns the SVG icon markup. In most cases, the SVG icon is injected in template files or via hooks and filters. In some cases, the SVG icon is injected via JavaScript.
  • Default markup looks like this: <svg class="icon icon-name" aria-hidden="true" role="img"> <use href="#icon-name" xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="#icon-name"></use> </svg>.
  • Note that we could use the absolute path to the SVG file in the href attribute of the use element. In that case:
    • there is no need to inject icons via the wp_footer hook.
    • The svgxuse JS polyfill must be used, because Internet Explorer doesn’t support external files referenced in the <use> element.
    • This method helps caching the SVG sprite file.
  • By default, all icons are decorative, but I insisted we show how to use non-decorative icons in an accessible way. Check the examples in the aforementioned twentyseventeen_get_svg() function.
  • We replace the default icon for supported social media links by using the walker_nav_menu_start_el filter.

Open source rocks

WordPress default themes are one of the best themes out there and they set an example how to use new WordPress features. The reason for this is simple.

  • Default themes gets lots of love and attention.
  • Many talented people contribute to default themes. Twenty Seventeen had over 100 contributors and we thank you all!
  • Default themes are tested before release in many platforms and browsers. And default themes are used on so many sites that any remaining bugs will be found after the release.

Building default themes really is a community driven project. I’d like to say extra thanks for couple of people.

Special thank you

Any web project needs good leadership, design, and code. Those were all covered in Twenty Seventeen.

  • David A. Kennedy was leading the project and kept everything rolling. He had a really friendly touch and he was open to ideas. At the same time he wasn’t afraid to make decisions; for example, a flexbox layout was rejected for this theme.
  • Mel Choyce created the modern, business looking design. She wrote a great article with her behind the scenes take.
  • Laurel Fulford was the primary coding lead. She seem to have a solution for every new feature and brought Mel’s design to life with detailed code.

Last but not least, remember Morten Rand-Hendriksen, the one that opened the SVG icon issue that caught my eye?

He was pretty happy with the end result.

Who knows if I would’ve contributed if it wasn’t for him posting that. Remember, reporting issues and bugs is contributing too, and can inspire first-time contributors like me to stop sitting on the sidelines and finally get started with core contributions.