About GitHub repository organisation and commit handling.
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 contributing to Pixelgrade repositories.
Branches
The main branch – As the main branch we use the theme name, despite everybody uses the
master as 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 branch
the_theme_name – this one will be deployed on SVN.
- The branch
self-hosted – 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 the development named
dev
- One for wordpress.org production version
wporg
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
Read More