Version Control

Engineering Best Practices
Search…
Introduction
Tools
Version Control
We version control all projects at XWP using Git. Version control allows us to track codebase history, maintain parallel tracks of development, and collaborate without stomping out each other’s change
Structure and Package Management
We structure our projects in such a way that we are not version controlling third party code, rather, they are included via a package manager. For PHP, we use Composer to manage PHP dependencies (also see package managers) e.g. WordPress core itself, plugins, and themes. Dependency management structuring is explained more in the Structure section.
We also do not commit compiled files (JS/CSS). This saves us from having to deal with people forgetting to compile files and large merge conflicts. Instead, we generate compile files during deployment.
Git Workflows
It is critical that you are comfortable with Git: read the book! We encourage people to use the command line for interacting with Git. GUI’s are permitted but will not be supported internally. For more information on Git:
​Hello World | GitHub Guides​
​Understanding the GitHub Flow​
​Forking Projects | GitHub Guides​
​A successful Git branching model​
Commits
Commits should be small and independent items of work, containing changes limited to a distinct idea. Distinct commits are essential in keeping features separate, pushing specific features forward, or reversing or rolling back code if necessary.
Do not wait more than a day to push commits. Push early and push often. Not only is it important to show progress for our work, it's also important for collaboration — when you sign off for the day another engineer may want to pick up where you left off, or do an early architectural review but that's not possible if you don't pushed up your latest work in progress.
Try to keep your commits as logically self-contained as possible. If you have made a lot of changes which you have not committed yet, you can step through the changes via git add -p to selectively stage chunks for committing. In this way you can group your changes into commits. Using git add -p is also just plain handy to stage changes for commit in general because it helps prevent accidentally committing something you do not intend. For the same reason, git commit -a should be avoided because you don't have the explicit step to review what you are committing. Remember you can do git diff --staged right before commit for one last review.
Commit Messages
The first line of a commit message is a brief summary of the changeset, describing the expected result of the change or what is done to affect change.
1
git log --oneline -5
2
​
3
# fca8925 Update commit message best practices
4
# 19188a0 Add a note about autoloading transients
5
# 9630552 Fix a typo in PHP.md
6
# 2309e04 Remove extra markdown header hash
7
# 5cd2604 Add h3 and h4 styling
Copied!
This brief summary is always required. It is around 50 characters or less, always stopping at 70. The high visibility of the first line makes it critical to craft something that is as descriptive as possible within space limits.
1
git commit -m "Add an #Element.matches polyfill to support old IE"
Copied!
Separated from the summary by a blank line is the longer description. It is optional and includes more details about the commit and its repercussions for developers. It may include links to the related issue, side effects, other solutions that were considered, or backstory. A longer description may be useful during the merge of a feature branch, for example.
1
git commit
2
​
3
# Merge 'feature/polyfill' into gh-pages
4
#
5
# matches and closest are used to simplify event delegation:
6
# http://caniuse.com/#feat=matchesselector
7
# http://caniuse.com/#feat=element-closest
8
# Promise and fetch are used to simplify async/ajax functionality:
9
# http://caniuse.com/#feat=promises
10
# http://caniuse.com/#feat=fetch
Copied!
Write your commit message in the present tense: "Fix bug" and not "Fixed bug". This convention matches up with commit messages generated by commands like git merge and git revert. Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
You may also see Core Handbook on Commit Messages​
Bonus points are given for starting the commit message with an applicable emoji when the code is pushed to GitHub and the client is OK with them:
:art: 🎨 when improving the format/structure of the code.
:racehorse: 🐎 when improving performance.
:non-potable_water: 🚱 when plugging memory leaks.
:memo: 📝 when writing docs
:bug: 🐛 when fixing a bug
:white_check_mark: ✅ when adding tests
Merges
In order to avoid large merge conflicts, merges should occur early and often. Do not wait until a feature is complete to merge main or develop back into it the branch. Merging should be done as a non-fast-forwards (--no-ff) to ensure a record of the merge exists. However, all merging should be done by means of pull requests, so you don't need to worry about non-fast-forward merges — this doesn't apply to the preview branch, which is a throw-away branch anyway.
If your commits haven't been pushed yet for others to see, it can be a good idea to update your branch from main by means of git rebase main. This prevents your branch from getting cluttered with merge commits from main. Be careful if you rebase commits after having pushed to a remote, as if others have the feature branch on their machines, they will likely get ugly merge conflicts when they try to update their feature branch. This is because git-rebase rewrites the history. (These same cautions go for using git commit --amend.)
When things are absolutely ready to go (i.e. it has passed code review, QA and UAT), we'll then merge the pull request.
When a merge is made into main and the project uses semantic versioning, then the merge should be accompanied by a Git tag.
Protecting the main Branch
We recommend for all repositories to be configured so the main branch is protected to prevent direct pushes. All merges should be made through a pull request, which ensures all code changes are peer reviewed before merging to prevent unintentional code reversions. Additionally, protecting branches provides the following benefits:
Prevents the main branch from being accidentally deleted by other engineers
Prevents force-pushes to the branch, overwriting the history
Themes
All new development should take place on feature branches that branch off main. When a new feature or bugfix is complete, we will do a non-fast-forward merge from that branch to staging or preview to verify the feature or fix on the stage environment.
When things are absolutely ready to go, we’ll deploy the feature or fix by performing a non-fast-forward merge from that branch to main
Branching
All theme projects will treat the main branch as the canonical source for live, production code. Feature branches will branch off main and should always have main merged back into them before requesting peer code review and before deploying to any staging environments.
All staging branches will branch off main as well, and should be named preview, staging or stage-{environment} for consistency and clarity. Staging branches will never be merged into any other branches. The main branch can be merged into both staging and feature branches to keep them up-to-date.
Complex Feature Branches
In some cases, a feature will be large enough to warrant multiple developers working on it at the same time. In order to enable testing the feature as a cohesive unit and avoid merge conflicts when pushing to staging and main it is recommended to create a feature branch to act as a staging area. We do this by branching from main to create the primary feature branch, and then as necessary, create additional branches from the feature branch for distinct items of work. When individual items are complete, merge back to the feature branch. To pull work from main, merge main into the feature branch and then merge the feature branch into the individual branches. When all work has been merged back into the feature branch, the feature branch can then be merged into staging and main as an entire unit of work.
Deleting or Archiving and Deleting Branches
This workflow will inevitably build up a large list of branches in the repository. To prevent a large number of unused branches living in the repository, we’ll delete or archive and delete them after feature development is complete.
Deleting branches
When projects use non-ff merges to main, we can safely delete feature branches because all commits are preserved and can be located from the merge commit.
Move to another branch (doesn’t matter which): eg. git checkout main
Delete the branch (both on local and remote): git branch -D branch-name; git push :branch-name
Archiving and Deleting branches
When projects use squash merges to create a more streamlined history in main, we should archive branches before deleting them to preserve the commit history. Branch tag archives also prove a useful history of branches, in case a specific branch is needed later.
Move to another branch (doesn’t matter which): eg. git checkout main
Archive the branch: git tag archive/branch-name branch-name
Delete the branch (both on local and remote): git branch -D branch-name; git push :branch-name
Push the archive tag: git push origin archive/branch-name
Plugins
Unlike theme development, the main branch represents a stable, released, versioned product. Ongoing development will happen in feature branches branched off a developbranch, which is itself branched off main. This pattern is commonly referred to as the Gitflow workflow.
Branching
New features should be branched off develop and, once complete, merged back into develop using a non-fast-forward merge.
Deploying
When develop is at a state where it’s ready to form a new release, create a new release/<version> branch off of develop. In this branch, you’ll bump version numbers, update documentation, and generally prepare your release. Once ready, merge your release branch (using a non-fast-forward merge) into main and tag the release:
1
git tag -a <version> -m "Tagging <version>"
Copied!
Note: Once a version is tagged and released, the tag must never be removed. If there is a problem with the project requiring a re-deployment, create a new version and tag to reflect the change.
Finally, merge main into develop so that develop includes all of the work that was done in your release branch and is aware of the current state of main.
You can use the svn-push script in wp-dev-lib to facilitate the syncing of plugins to WordPress.org. This integration can even be automated by Travis CI.
Semantic Versioning
As we assign version numbers to our software, we follow the Semantic Versioning pattern, wherein each version follows a MAJOR.MINOR.PATCH scheme:
MAJOR versions are incremented when breaking changes are introduced, such as functionality being removed or otherwise major changes to the codebase.
MINOR versions are incremented when new functionality is added in a backwards-compatible manner.
PATCH versions are incremented for backwards-compatible bugfixes.
Imagine we have written a new plugin. We might give the first public release version 1.0.0. After releasing the plugin, we decides to add some new (backwards-compatible) features, and subsequently releases version 1.1.0. Later, we find a bug and report it via GitHub; no functionality is added or removed, but we fix the bug and releases version 1.1.1.
Down the road, we decide to remove some functionality or change the way some functions are used. Since this would change how others interact with this code, he would declare this new release to be version 2.0.0, hinting to consumers that there are breaking changes in the new version of his plugin.
Change Logs
If your plugin is being distributed, it’s strongly recommended that your repository contains a CHANGELOG.md file, written around the Keep A Changelog standard.
Maintaining an accurate, up-to-date change log makes it easy to see – in human-friendly terms – what has changed between releases without having to read through the entire Git history. As a general rule, every merge into the develop branch should contain at least one line in the change log, describing the feature or fix.