We version control all projects using Git. Version control allows us to track codebase history, maintain parallel tracks of development, and collaborate without stomping out each other’s changes.
The key philosophy that drives our repository structure is we don’t version control things that are version controlled elsewhere. This means we don’t version control WordPress core files or third party plugins.
The git repo structure is as follows always:
|- wp-content/
| |- plugins/ ___________________________ # Include in this folder any plugin you develop or mod.
| |- index.php _______________________ # Silence is golden
| |- themes/ ____________________________ # Include in this folder any theme or child theme you develop or mod.
| |- index.php _______________________ # Silence is golden
|- .gitignore ____________________________ # Standard Saucal GitIgnore file (see below)
.gitignore file should be
# Ignore everything in the root except the "wp-content" directory.
/*
!.gitignore
!wp-content/
# Ignore everything in the "wp-content" directory, except the "plugins"
# and "themes" directories.
wp-content/*
!wp-content/plugins/
!wp-content/themes/
!wp-content/index.php
# Ignore everything in the "plugins" directory, except the plugins you
# specify (see the commented-out examples for hints on how to do this.)
wp-content/plugins/*
!wp-content/plugins/index.php
# !wp-content/plugins/my-single-file-plugin.php
# !wp-content/plugins/my-directory-plugin/
# Ignore everything in the "themes" directory, except the themes you
# specify (see the commented-out example for a hint on how to do this.)
wp-content/themes/*
!wp-content/themes/index.php
# !wp-content/themes/my-theme/
# !wp-content/themes/my-child-theme/
.DS_Store
*.lessc.css
config.codekit
node_modules/
Commits should be small and independent items of work. Distinct items of work are essential in keeping features separate, which will aid in reversing or rolling back commits if necessary or pushing specific features forward.
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 another developer may want to pick up where you left off, but this is not possible if you have not 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.
The gist of a great commit message is this:
Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary but most likely necessary if you want to be a good citizen! Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.
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
All projects will treat the master branch as the canonical source for live, released, stable, production code.
Projects will have a staging branch off of master where feature branches get merged and integrated before being merged into master. This branch basically represent the status of the latest code in the staging enviroment.
Take a look at understanding the GitHub Flow which is a more simplified than a more traditional Git branching model.
In order to avoid large merge conflicts, merges should occur early and often. Do not wait until a long-in-development feature is complete to merge master into it.
When things are absolutely ready to go (i.e. it has passed code review and QA), merge the feature branch into staging.
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 preview and master it is recommended to create a feature branch to act as a staging area: this is the primary feature branch. 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 master, merge master 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 preview and master as an entire unit of work.
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 them after feature development is complete. Since all feature branches should get merged by means of pull requests, there will be a persistent reference to the original branch in the pull request. So after merging the pull request, delete the branch from Git. It can be restored later via the pull request.
In the event that a client or third-party developer makes a change to any file included in the repository, we’ll capture the diff of their changeset and import it to our development repository by:
master or staging depending in which enviroment the change happenedBe aware that this syncing process should happen before you merge any feature branch or new work into any phase, otherwise the diff would be different than what you might expect. At the end of this process your master or staging branch should have a clear copy of the enviroment codebase before any work you’ve done that’s waiting to be deployed.