Commit early, commit often
Naming a repository follows this pattern:
with allowed characters
technology is usually
wordpress, but can be some other PHP framework like
Your repository should consist of several main branches:
staging and some optional:
feature (depending on the project).
Before each project starts, the lead developer should fill out the Project Setup Sheet that specifies what language and framework will be used, versions, necessary scripts, deployment setup, server requirements, etc.
Modified Git flow
Before the DevOps set up deploy scripts and any kind of CI/CD (Continuous Integration/Continuous Deployment), a
master branch should be filled with the initial setup. Ideally, this should contain a renamed theme using the boilerplate and, possibly, the minimum necessary plugins so that the developers can work without always having to merge the branch with the plugins in it.
In the case that the
master branch contains only the theme, a feature branch called
feature/add-update-plugins which holds the necessary plugins should be made. It is used for updates and for adding new plugins from the wordpress.org repository or paid plugins, such as ACF Pro.
Always branch off the
master branch into a feature branch, and never commit directly to it. The master is usually protected against that, but better safe than sorry.
The master branch is always deployable
When submitting a patch, fix or a new feature, always open a new branch and pull from the
master branch. For example, a feature would be:
After that, create a pull request to
preproduction), and assign a reviewer.
Every merge is done via pull requests. Manual merges are prohibited (or not possible in the case of a
If the branch you want to work on depends on a branch that is still being worked on, pull the changes from that branch into your branch to get updates (cherry pick). Be sure to track the changes on that branch.
staging branch is usually connected with a staging server using build and deploy scripts. After the tests are completed, the features should be merged with the
master branch has to be tagged according to SemVer before the release. A short introduction to SemVer can be found here.
master branch is usually protected so that it is not possible to merge directly to it. Merges to
master are done periodically when new features are ready to be released.
preproduction branch should be linked to the preproduction server so that the client can enter content that will be merged to the production once ready. The
preproduction is a 1:1 clone of the
master and should contain only working and production-ready code.
Once the project is in production, you should make a branch from the
master branch every time you create a feature. When you think it's ready, submit a PR to the
staging branch, and tag (label) it accordingly. Once the testing is completed and feature branches are ready, the lead developer will deploy them to the
It's the same with the pre-release. If you are working on a feature that depends on another feature merged to the staging branch, pull that branch to your branch to get the desired features.
In case of conflicts, don't panic
Once you have fixed the possible issues in the PR, make sure the conflicts are fixed.
Don't fix conflicts on GitHub. Use terminal. Say you have two PRs open—one to the
staging and one to the
master branch. In case of conflicts on the PR toward the staging branch, you will want to do the following:
git checkout staging git merge --no-ff feature/conflict-branch-name git push staging
Once you have merged the feature branch to staging, you'll have conflicts. Fix them, commit them, and push to staging. This won't impact the other PR to the master. If you use the first GitHub suggestion or their edit tool, you will merge the entire staging branch to your feature branch, and that will impact the PR to the master branch (a bunch of unwanted commits and messed up history).
If you're not sure what to do, ask someone who is. 🙂
Do not submit PR that has over 100 changed files
There are many reasons why submitting a huge PR is bad. The first one is that it can crash your browser if you are inspecting it on GitHub. The second one is that it will take a lot of time to review it, and the reviewer will most probably just skim through the PR because they have other things to do. When submitting a PR, ask yourself, "Would I want to review this?"
Also write good Git commit messages. Commit messages should be short and clear. Write the subject in the imperative mood. A properly formed Git commit subject line should always complete the following sentence:
If applied, this commit will *your subject line here*
More on writing good commit messages can be found here.
Make small commits, following the Single Responsibility Principle on Git. This makes commits easier to review when doing pull requests, and it's easier to see what is going on when something goes wrong.
Don't use git add . Review what you're adding to your repo—this is the #1 cause of making unwanted changes.
Here you can watch a presentation on common issues and reasons for writing good commit messages.
Releases are deployable software iterations you can package and make available for a wider audience to download and use.
When deploying the site to production, it is expected that a bundled GitHub release is created. Releases also help us compare with previous iterations.
Releases are based on Git tags, which mark a specific point in your repository's history.
Each Pull Request preceding a release needs to be tagged with the upcoming release tag (milestone). Although a final release can be created without this step, it is required so we can see all related steps and branches leading to the release. Tagging also provides an option to automatically add the markdown for all the merged pull requests from the diff and contributors of the release.
When deciding which tag to chose for the next release be sure to follow the SemVer guidelines.
For the actual step-by-step guide it is best to follow the Creating a release official guide.
When creating a release be sure to create a new tag with the same SemVer as the preceding PRs!
Releases usually contain either fixes, updates, additions or all of the above. So for the actual description it is best to create a section for each.