Commit early, commit often
Naming a repository follows this pattern:
{technology}-{project name}
with allowed characters [a-z\-]. technology is usually wordpress, but can be some other PHP framework like laravel or symfony.
Your repository should consist of several main branches: master, develop, staging and some optional: preproduction, edge, and feature (depending on the project).
Project setup
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:
feature/adding-new-user-roles.
After that, create a pull request to staging and master (and/or preproduction), and assign a reviewer.
Every merge is done via pull requests. Manual merges are prohibited (or not possible in the case of a master branch).
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.
The 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 and preproduction branches.
The master branch has to be tagged according to SemVer before the release. A short introduction to SemVer can be found here.
The 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.
The 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 master, preproduction, and 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 master branch.
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.
Release Procedure
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.
For example:
Official docs: