Igoo Git-flow

Introduction

In the past, IGOO has suffered various problems when dealing with the process of producing and shipping code; new features, hot fixes and, in the case of Magento sites, 3rd party modules can often be held up or produce unexpected results during the development process.

This git-flow process has been designed to try and mitigate those issues and introduce a new culture of self documenting, outlining what we did and when as well as making the commit log more useful; especially in regard to the migration to Github.

All examples will include a command line example but if you wish to do the same in a GUI app that's fine as long as you know you're performing the equivalent action.

Process

A traditional gitflow will have a number of branches in play at any one time. The first difference to this system is there is no dedicated develop branch. This is because whilst it would be nice to follow the convention, in an e-commerce / agency environment clients often change their minds and unforeseen circumstances are common.

The main endeavours of the process are:

• Staying out of the master branch as much as possible; we only merge into it when we want to deploy to production.

• To mirror the way features and sprints are agreed and realised with the client.

• To be flexible enough for minds to be changed and for unexpected circumstances to be accommodated.

Features

When we make tasks to create features in Meistertask (MT) we need to consider how narrow the scope of that task is in order to keep conflicts to a minimum (or at least very easy to resolve when they happen). The separation of concerns may include front-end vs back-end or areas of the site.

For example, changing the copyright notice and the social media links within a footer would be two tasks that would involve working within the same template file. It's going to be easier to have a task that covers both of these and contain check boxes (which we can can complete with the commit message) rather than have both small items as separate tasks.

At the same time we don't want to make the scope too wide; a refactoring task of a number of areas could mean that one task is overseeing a lot of code with different responsibilities and we want to be able to leave out a feature if it didn't quite work out the way we wanted.

Creating a feature

(Note: If you have the latest version of https://github.com/igoouk/shell-config then you can use the newbranch function. To use type newbranch followed by a space and the name of your branch [see below].)

Update master. In the command line you'll want to be in an up-to-date master first:

git checkout master

git pull

Then create the new branch starting with feature/ followed by the task ID, an underscore and a short description. For example:

git checkout -b feature/qAM7ewA3_TrainingIssue

If you make a mistake, you can rename it with:

git branch -m old_branch new_branch

Note if it's an internal issue regarding a bug or error message, use the github issue number rather than the MT reference.

When you feel it's ready to be put forward for staging, add the files and push the branch up to github whilst logged into the Github website.

git add . << This means add everything from my current dir

git add file.txt << add a single file.

git add app/code/Igoo/OurAmzingModule << add a directory

git status will reveal the files that are staged. We now want to commit these with a meaningful message and, potentially, a reference to the MT task. To complete an entire task you use the following format in the commit message #qAM7ewA3. To check something off, we add a colon and an item number like so: #qAM7ewA3:1.

In the image below you can see we have one checklist item. Let's check that off now!

git commit -m "Added training file to repo for task #qAM7ewA3:1"

git push or git push --set-upstream origin feature/qAM7ewA3_TrainingIssue for the first time. (git will tell you this anyway.)

You should see a response like:

Total 0 (delta 0), reused 0 (delta 0) To git@github.com:igoouk/wongsjewellers-co-uk.git * [new branch] feature/qAM7ewA3_TrainingIssue -> feature/qAM7ewA3_TrainingIssue Branch feature/qAM7ewA3_TrainingIssue set up to track remote branch feature/qAM7ewA3_TrainingIssue from origin.

Now log in to Github and navigate to the correct repo. You should see a yellow box with a green button that says "Compare & pull request", click that button.

You will be presented with a page entitled "Open a pull request"

#####!!! IMPORTANT !!! Change the base to the release branch (which hopefully has been created already but if not make one). We DO NOT want to merge into master branch here.

In the comments, clear all the Github template stuff out if any is in there, and provide a link to the issue like so:

Connects to https://www.meistertask.com/app/task/qAM7ewA3/training-issue

Incidentally, we should now be able to see by now in MT our checklist item ticked off along with a link to the changes we made in github. (Requires Github integration activating.)

Back in Github, we need to finish our pull request. Add a reviewer (if this is something that's been earmarked for code review), the relevant tags and, MOST IMPORTANTLY, the release milestone.

If you don't add it to the milestone, it may never get to staging and all your hard work will have been for nothing.

Finish off by clicking the "Create pull request button" and you're all done!

Hot fixes

Hot fixes are pretty much the same but we are using a github issue to document it internally (out of sight from clients) and we use hotfix/ as the prefix.

Every release will end with .0, hotfixes increment this number. If we change code directly on the server then what was changed should be reflected in a hotfix and merged into master so the change doesn't get overwritten on the next deployment.

Hotfixes need to be included in release branches before deploying to staging by merging the same branches into it. Please include them in the active milestone when done so they're not forgotten about.

Third party modules and Magento upgrades

Please follow the same procedure as features and add the whole module as one commit so it can be reverted.

When upgrading a module, revert the previous version's commit first (git revert a123456) and then add the new code. This helps ensure we can remove the module cleanly.

Please use uppercase comments in your git commits:

MAGENTO 1.9.3

AHEADWORKS LAYERED NAVIGATION 1.2.3

Bugs

We may identify bugs but not necessarily want them as a hotfix. Follow the same procedure as features but use the prefix of bug/ followed by the Github issue number and short description. E.g.

bug/55_SqlSyntaxErrorOrAccessViolation

In the pull request include the text:

Connects to #55

This will link the two things together in Github.

Magento Core bugs

If dealing with a Magento core bug we want to be able to search for them at a later date. To achieve this, begin the github issue with either MAGENTO2COREBUG or MAGENTO1COREBUG and a note of when it will be fixed, if known.

This way, when the fix comes through to a new version, we can revert the commit that we did to mitigate the problem originally.