Git Workflow

Owned by Will Hastings (Unlicensed)
Last updated: Jan 15, 2021 by Jason Blanda (Unlicensed)
4 min read

Introduction

This documentation is designed to guide developers through the development workflow process at Kalamuna.

Core Stages

Kalamuna utilizes a traditional three main stage workflow process, dev, test, and live. Where dev is merged into test, test into live, which is managed via Pantheon.

Having the main stages on Pantheon means there is no need for corresponding branches in git. 

All work begins and ends on master and that branch is pushed to dev. 

Pantheon then manages the rest of the process, dev -> test, test -> live.

Cloning the Repository

Most projects will have their own GitHub repository. 

In some cases projects will not have their own GitHub repository, in which case the codebase can be cloned from Pantheon.

To obtain the codebase and begin development:

  1. Clone the Repository locally
  2. composer install
  3. npm it  
  4. lando start to start lando
  5. lando pull  to pull database (files if needed)

Typically, pulling the dev database is preferred. 

Branching Structure for Development

Work should never take place directly on the master branch.

New branches should be created, work should take place, if necessary multi-devs generated and pull requests created to merge code into master.

Branches 

Branches are used to develop any new functionality, fix bugs and update modules/core.

A branch's life-cycle is from the beginning of the development until all work has been completed and the corresponding ticket has been resolved. 

Once the corresponding ticket has been resolved, the branch dies and additional work for a given feature will require a new ticket and a new branch.

Creating a Branch

Branches utilize a specific naming convention to keep development uniform across all Kalamuna projects.

Branch names should be in the following format:

proj-123

Where proj indicates the project abbreviation code in Jira and the 123 corresponds to the Jira ticket number where the task was requested.

This is done for two main reasons:

  1. Branches can easily be traced back to their initial request via the ticket number.
  2. Branch names will be within the 11 character limit for Pantheon Multi Devs.

Commit Structure

Commits should follow a specific naming convention to create a commit log that is legible and easy to follow.

Creating a Commit

Before you create a commit, ensure that you are only adding files you have made changes to. 

This can be an issue especially with the Drupal Configuration Management system.

A visual commit tree can be helpful to check staged files against actual changes.

Visual Studio Code

As an example, we’ll look at the visual tree for Git within Visual Studio Code (Though you may find other programs have similar functionality).

We can see all the files being affected in this commit on the left, changes to a selected file on the right and can revert or add each file to the commit if it truly is a part of our commit.

This keeps from accidentally modifying, committing and causing conflicts between other branches. Only commit what needs committed.

Commit Naming Convention

Commits should be made in the following way:

“proj-123 My atomic commit message in present tense” 

Where proj is the project abbreviation code and 123 is the ticket number from Jira.

Commits should have a detailed, yet brief, message about the changes.

The following are examples of good commit messages:

  • Changes the header navigation order
  • Adds paragraphs module
  • Tweaks the search api’s html preprocessor
  • Theme adjustments to the Homepage Hero

The following are examples of bad commit messages:

  • Navigation Changes ← In what way?
  • Module Installation ← What module?
  • Search Adjustments ← What adjustments
  • CSS Tweaks ← What was changed and where?

This creates a clean commit log where development can be traced.

This also makes referencing previous work easier if it needs completed on another project.

NOTE: Where possible, please try to make small, atomic, commits as opposed to one large commit with illogical groupings of work.

Pull Requests

Pull Requests should also follow specific conventions. 

Pull request names should reflect the work that is included in the PR itself.

Detailed descriptions within PR’s is not totally necessary if documented in Jira. 

A link to the ticket should be added to the description so reviewers can check the PR against the ticket and review QA notes.

Multi-Issue Branches

There can be cases where a large new feature is being pushed forwards. For example, a menu that needs navigation hierarchy, theming, responsive breakpoints, JavaScript interactions. Implementing all of these features in one issue is a lot.

In this case, have a multi-issue branch (proj-123), and have multiple branches merged into the larger branch (proj-124 > proj-123). For example...

  • proj-123 Menu System
    • proj-124 Menu Hierarchy
    • proj-125 Add responsive breakpoints for the menu
    • proj-126 Add JavaScript interactions for the menu

Once the smaller tasks are complete, merge them into the larger issue branch.

To make QA easier on the clients, you can choose to name the “proj-123” branch more semantic, like “menu”. Keeping the branch name the same as the issue id is a convention.