Maintainable WordPress Development 2/3: Version Control & Things To Watch Out For

In our previous WordPress development blog post we mainly talked about tools that you can use when developing a WordPress theme, plugin or any other web related project. We’ve also mentioned how you can use those same tools to automate parts of the development process. Now, in this blog post you’ll discover what to watch out for when implementing version control into your project. Equally, what to spot with version controlling the project itself and cooperating with your team members. Let’s get down to our second maintainable WordPress development post.

Code versioning and cooperation between team members are two very, very important things when developing a project of any kind. In order to properly implement those two into your development workflow you’ll first need to choose the tools. Yes – another set of tools that you’ll want to use depending on your needs. In the previous blog post, I mentioned some of the tools we like to use and those are:

Tools are important but so is the proper strategy. When I say proper strategy I actually mean a proper way of implementation and usage of those tools within the development workflow while avoiding unnecessary setbacks simply by asking the right questions. So let’s talk little bit more about that.

Implementing the Version Control

First of all, why Git? Because Git is, without doubt, is the most popular and the best free version control system on the market. Most of you have heard of it and I bet that most of you use it. If not, you really, really should because such popularity brings tons of (free) resources that you can use. Perfect if you’re just starting to get to grips with it or if you wish to learn more advanced aspects as well. Now that we’ve selected the VCS (Version Control System) the next step is to choose a strategy. A Git workflow, that you’ll use during the project development and here’s a short list of the most popular workflows at the moment:

Centralized Workflow
Feature Branch Workflow
Gitflow Workflow
Forking Workflow

If these workflows are new to you and/or you don’t know anything about them you should definitely read the “Comparing Workflows” article written by Atlassian. This is a really crucial step since the wrong workflow can lead to longer development time which then results in bigger costs and unsatisfied clients. For example, implementation of a complex workflow like the Gitflow Workflow within a team that doesn’t know hardly anything about version control can prove to be a complete disaster. This is because it will take more time for the team to learn the workflow than to actually develop the project. Also, some projects simply don’t require such a complex workflow so be sure to think about what you actually need.

Here at Slicejack we use the Feature Branch Workflow where every feature gets its own branch and gets developed within it. It’s a fairly simple workflow that enables us to organize the code much easier. It also works great with some other tools we use like JIRA (issue tracker) and BitBucket (Git repository host). We’ll talk little bit more about those two in the next WordPress development blog post where I’ll talk about project maintenance. What I will say now is just how great those tools work together. You can literally connect a BitBucket repository with a JIRA project and then create feature branches right from the JIRA issue related to that project. You’ll then be able to see all branches and commits made against those branches related to that very issue. How awesome is that? 🙂

Another thing to watch out for is the .gitignore file. Almost every Git repository setup starts with one. When working on a WordPress development project, the contents of that file may vary depending on what you need and what tools you’ll use. Here are just some of the things that you need to watch out for when building the .gitignore file:

What directory structure do you wish to use?
Do you wish to version control the WordPress plugins?
Do you wish to version control the WordPress core?
Are there any tools (like NodeJS) that will create their own directories within the project that you don’t wish to track?

Since we’ve opted to use the default WordPress directory structure, certain node modules for our development scripts DON’T, so the version of the WordPress plugins of our .gitignore file looks fairly similar to the .gitignore file provided by WP Engine which can be found here. This file is important since there are tons of files that simply don’t need to be or should not be versioned in the first place. Wrong .gitignore setups can lead to repositories being 200MB (or more!) in size in a very short period. That’s just insane if you’re working on an ordinary WordPress theme or a plugin.

After the repository setup comes the development and there are a few things that you should be watch out for when developing any sort of WordPress project.

Things to watch out for

With every project you will, hopefully learn something new. You’ll know what to avoid or what to do when you start developing your next project. The same thing happened to us and here are a few things we’ve noticed.

Avoid magical GUI wizards

We’ve never used them but we needed to update and maintain a smaller number of projects that were developed this way. Now, whenever you use some sort of a “magical” GUI enabling you to create custom meta boxes, fields, post types or taxonomies without a single line of code, you’re making your project much harder to maintain and to cooperate on. Why is that? Because most of those plugins (or maybe some specialized apps) store the whole configuration within the database. This would require you to:

Send new versions of the database to every team member after every change you make (or a XML file which team members then need to import)
Manually deploy configuration files or parts of database to production/staging environment
Manually create a field or two on the production/staging environment
Manually create backups of all XML configuration files so you can be sure you can, somehow, revert changes made on the local, staging or production environment

You should avoid that kind of development whenever possible. Mistakes do happen and with every manual change risk of making some sort of mistake gets bigger.

Think multilingual

Every theme and every plugin has at least a few static strings that aren’t manageable by the administrator and will probably stay that way. Regardless of developing a theme (or a plugin for that matter) that is multilingual or not, you should always prepare those strings as they’ll be translated sooner or later. When and if that day comes, it’ll be much easier to translate the site. If you don’t prepare the strings you’ll find yourself painstakingly going through every php file searching for those strings which, of course, takes time. What’s more, it is highly likely you’ll probably miss at least one or two in the process. In order to properly manage those strings make sure you read the official WordPress i18n guide.

Follow the standards

As we come towards the end of this WordPress development post, here’s one last suggestion. Finally, follow the standards since standards are there for a reason. Standards help you and your team in many ways. These include, but not limited to:

Clean code
Better code understanding and maintenance
Better code organization
Better cooperation
Reduced number of merge conflicts

Some editors and IDE’s even allow you to install certain plugins that use some kind of linter to validate your code against WordPress or pretty much any other standard out there which can prove to be very useful.

So it’s over to you. We’d love to know your thoughts on this WordPress development post.