This page is out of date and needs reviewing.

All our code is version controlled using Git most of which is hosted on the Agile Collective GitLab server:


Git is generally pre-installed with most Linux distributions and on MacOS. It may be worth updating to the latest version however.


To install the latest version of git you can use Homebrew:

brew install git

Git branching

We use a simplified Git Flow branching methodology:

There are 2 main branches: master and develop. Master is the production branch, the live site is always checked out on this branch and only code that is ready to be deployed should be merged into master. This ensures that the master branch is always deployable. The develop branch is used for long running development projects, often with more than one developer merging their changes into the branch. Once the work has been signed off for deployment to live, the develop branch is merged into master, which is then deployed to the production site.

Developers make changes to feature branches. These are taken from the develop branch and once the feature has been developed and tested, merged back into the develop branch. Feature branch names start with 'feature/' and then a ticket number ID (if this exists) and finally a short description of the feature; e.g. feature/12345-fancy-new-feature.

Hotfix branches are used for security updates and bug fixes. These are taken from the master branch and, once the update has been tested or the bug fixed, merged into both the master and develop branches. Hotfix branch names follow the same naming convention as feature branches, but start with 'hotfix'; e.g. hotfix/12345-short-bug-description or hotfix/security-updates-nov-2018.

Sometimes we will want to do periodic releases, taking a number of changes and deploying them together, in which case a release branch can be used. A release branch is created from develop, feature branches are then created from the release branch and merged back into the released branch. Once the release branch is ready for deployment, it can be merged into master and develop.

Commit messages

Ideally git commit messages should stick to the recommendations. Where the commit refers to a support ticket or project task the message should start with a hash followed by the ticket number, e.g. #12345. After that the message should begin with one of four imperative verbs:


git commit -m "#12345 Add ajax callback to number field"
git commit -m "#12345 Fix broken submit handler on donation form"
git commit -m "#12345 Update coffee module"
git commit -m "#12345 Change Sass for homepage header"

Messages should be concise and convey meaning to a user who has not seen the code before. A longer message may be added in a second line in the commit message so as to convey more detail on a particularly tricky commit. This can be done using the standard git commit command without the inline message. The longer commit message should be added on the third line, for example:

#12345 Add section about git message convention

Follows convention and is a recommendation to be ratified by the team.
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch feature/git_conventions
# Changes to be committed:
#       modified:   tools/

Git workflow recommendations

Usually we try to commit smaller chunks of code more often. This allows for easier git diff reading and code reverting. For example, when updating a number of Drupal modules as part of a maintenance cycle it is preferable to commit each updated module individually.

git add modules/contrib/coffee
git commit -m "Update coffee module"

This makes it much easier to git bisect later if an issue is found but its not known which module introduced the issue.

Committing SASS and compiled CSS

When committing SASS and CSS changes it is preferable to commit the compiled CSS separately from the SASS change. This is so that a git show command can easily display the SASS change without having to scroll past a massive compiled CSS file first.

git add themes/custom/site_theme/source/_patterns/00-base/15-typography/text/_text.scss
git commit -m "#12345 Update base typography"
git add themes/custom/site_theme/dest
git commit -m "#12345 Update compiled css"

When multiple people are making SASS changes to a theme at the same time, it is easy to run into merge conflicts on compiled CSS and SASS map files. In such case it is easier if a single person agrees to compile the SASS before deployment. An alternative solution is for neither person to commit compiled CSS until an arranged deployment, when someone compiles and deploys the changes and the other person pulls the newly compiled CSS before making any further changes.

Committing third-party code

We commit 3rd party code which is required to run the application, e.g. Drupal dependencies managed via Composer or a JavaScript library needed for the front-end managed by Bower, but we do not commit 3rd party code which is required for development, e.g. A Gulp plugin or the Behat executable. We use the 'development dependencies' feature of the package managers to facilitate this, e.g.


"require-dev": {
    "behat/behat": "3.3.1",


"devDependencies": {
    "yeoman-generator": "^0.23.3",

This requires the developer to be mindful of what they're committing though package managers can assist with the removal of development dependencies if required, e.g. using Composer the following command can be ran:


composer install --no-dev


npm prune --production


Drush is an exception to the development dependencies rule and is committed to the repository so Drush should be specified as a production dependency using Composer.

Deployment using git

We use a monolithic repository structure which makes deployment quite easy. Generally (unless a client's server has specific instructions) you would ssh into the remote server where the site is hosted and become the admin user on that server:

sudo -u admin -i

You would then cd into the correct directory (either production or staging) and pull the correct branch. The production environment should always use the master branch.

cd /var/www/
git status
git pull origin master

Stage maybe checked out onto feature or hotfix branches, but should be returned to master when no longer in use. This ensures that anyone looking to test something can be sure that stage is not in use if it's checked out on the master branch. If you wish to test something and the stage site is checked out on a feature branch then ask in chat if anyone is using stage for a specific site; running git log on stage should show who was last to commit changes. Stage sites should never be left on hotfix branches.

cd /var/www/
git status
git pull
git checkout feature/12345-my-feature

Once you've pulled the changes would then run any database updates or rebuild caches etc.

Repo structure for Drupal and other web projects

The following directory structure is used for our website repositories.

'Git ignored' files

We Git ignore .htaccess files, config that contain database and site specific information, and any uploaded file directories. The are example gitignore files for:

Last updated: