Contribution

Introduction

Our work is based on contribution, there is no project that we can do on our own, and even if we do so, we still need a second opinion.

But the contribution needs to be organized in order to help yourself later, it must be predictable and clear and this means that we need to follow some rules.

Any break of these laws should be sufficient enough to turn down a pull request!

Inspired by Chris Beams article How to Write a Git Commit Message we want some of these guidelines to be followed while contribute to Pixelgrade repositories.

Branches

Main branch

As main branch we use the theme name, despite everybody uses master as a main branch name, we like to keep it clear who is the master in every repo.

WordPress.com

A wordpress.com theme will be always split in two main branches:

the the_theme_name branch – this one will be deployed on SVN.
the self-hosted branch - which will keep our Shop version.

Plugins

For plugins, since we need to deploy the code on SVN, we keep two main branches:

one for development named dev
one for wordpress.org production version wporg.

Let’s define the battle zones

Question: If I want to contribute, which is the best way to do it?

The quick way: In case you need to apply a quick fix or some small patch you can simply patch it directly to the main branch.
The proper way If you want to add a new big feature or a considerable rewrite, you should definitely think about creating a new branch.

If you chose to contribute via a new branch, we would like you to:

keep the branch name as short as possible – I bet no one likes to commit with a command like git push origin #327-first-rework-wp-job-manager-paid-listings-templates
start the branch name with an issue ID – every new branch should have a related issue opened to document what should be achieved on this branch. By doing so, if someone else wants to work on the very same thing, you work together on the same branch and issue. Also, when you merge the branch, you can automatically close the issue.

Commit well!

Every time we add a commit we should think that other people might want to understand what your commit does. So you need to be explicit about it.

The first rule is to split the commit in 3 parts: a subject, a body and metadata.

The Subject

It is capitalized
It is less than 50 chars
It ends without a dot
Must start with imperative mood since you command what that patch will do when applied.

Example: Remove deprecated methods from functions.php

The Body

The body is the place where you can explain what the commit does.

Commit Metadata

All the references should capitalized and placed last(like Close #131). It is less important for another teammate to read who it will refer than what it does.

Optional templates

Every repo can also contain a readme template for issues or pull requests.

This template should be clear about what are the requirements and options when we create an issue or a pull request.

About the Tools

There are some arguments around the web about how to do a git commit and Chris Beams recommends to leave any IDE behind and try to use a primitive bash/terminal, this way you can understand better how git works.

At Pixelgrade, this is at the contributor’s will but you have been warned about the struggle.