EC Repos

Standard Branches

clone

• master: serves no purpose
• LIVE: Only for use as the currently running live site
• Releases (optional):
  • Branch from LIVE
  • Release-XXX: For merging feature branches into for testing on a Staging site
• Features:
  • Branch from LIVE
  • JIR-123-Description-of-Feature: Feature branch. Merged into Release-00x or dev when the feature is considered stable
  • Subfeatures
    • Branch from a Feature
    • JIR-123-JIR-124-Description-of-Subfeature

Grouping tasks into Releases

Jira

You can also use Jira to mirror these branches

• Releases are an optional addition to the system that make sense for projects where a lot of concurrent tasks are worked on
• When using Release branches, the Release represents a group of completed Features ready for testing.
• Features should only be merged into the Release once they're ready for testing - a Release should never have half-finished features merged into it.
• A Release must be deployed to LIVE as a whole package. When assigning Features to Releases make sure any dependencies are within the same Release, and also be aware that one unfinished feature will hold up the entire Release.
• Releases numbers should be incrememented as they're created (not their intended release order, as that can change)

Testing code on Staging

• If using a Staging site, it should be a git checkouted working copy of the Release or Feature you want to be tested.
• This allows for switching between Releases or Features as and when they're in development

Git Branch lifecycle

Working in Feature branches

1. git checkout LIVE to make sure you're branching from the live site
2. Create a new feature branch with git checkout -b JIR-100-Ticket-Summary
3. In Jira mark the ticket as In Progress
4. Commit early, commit often. The Feature branch can be in a broken state

Considerations:

• Each ticket should be its own git branch, prefixed with the Jira ticket number
• Multiple Feature branches can be worked on in parallel until they're complete
• Branch dependencies should be documented in Jira using Issue Links

Preparing completed features for Release

Note

Release branches are optional. If not using Releases the Feature can be merged into LIVE directly, but the same workflow below applies

• Add a new Release in Jira
• git checkout LIVE to make sure you're branching from the live site
• git checkout -b Release-XXX your new Release branch
• git merge your features you intend to deploy to LIVE
  • Make sure to add the Release to the ticket's "Fix Version" field
  • Remember to git branch -d the Feature branches after they've been merged in
• git commit any fixes into the Release branch that need to be made before going live

Considerations:

• This branch should represent everything that will go live. This branch should be checked out onto the Staging site for acceptance testing
• Ideally commits should stay inside the Feature branches, but I acknowledge that this is going to add a lot of overhead

Putting the Release live

1. git checkout Release-XXX
2. git merge LIVE to make sure any LIVE changes are in the Release
   • If these are significant, you might need another round of testing
3. git checkout LIVE
4. git merge Release-XXX
5. git tag Release-XXX
6. git branch -d Release-XXX
7. git push your LIVE branch and git pull it onto the server

Considerations:

• Once a Feature (via a Release) is merged into LIVE, that Feature branch is then considered immutable; new items should be new tickets/branches
• You may choose to tag the merge commit as the Release name for easy rollback

Subfeatures

Sometimes one feature will need to be separated out into smaller subfeatures, and therefore branches.

1. git checkout JIR-123-Ticket-Description to make sure you're branching from the parent feature
2. Create a new subfeature branch with git checkout -b JIR-123/JIR-124-Ticket-Summary
3. Commit into the subfeature branch, and feel free to re-merge the parent into the subfeature
4. Once the subfeature is complete, it must be merged back into its parent feature and then deleted

Considerations:

• The hierarchy should be clear in the JIR-123/JIR-124 branch name prefix
• We're allowing for 3 levels of branching, with a max name of JIR-123/JIR-124/JIR-125-Sub-Sub-Branch-Name
• The hierarchy is explicitly not coupled to Jira ticket types; the top level doesn't have to be an Epic, and the bottom level doesn't have to be a subtask
• Subfeatures must clearly depend on the parent feature to function
• Subfeatures cannot end up in the LIVE branch other than via their parent branch.

Hotfixes

Hotfixes are for quick fixes to urgent problems. They're intended to remove the overhead of Releases when time is critical

1. git checkout LIVE to make sure you're branching from LIVE
2. git checkout -b JIR-XXX-Problem-Hotfix to create the hotfix branch
3. Make changes in that branch
4. git checkout the branch onto a dev site for testing
5. git checkout LIVE and then git merge JIR-XXX-Problem-Hotfix
6. git branch -d your Hotfix branch
7. Push your changes to the live site

Considerations:

• A hotfix should address a discrete problem; if the scope is large you should use a Feature and follow the standard release procedure
• Hotfix branches are technically identical to Feature branches, so if the scope becomes large, it can be treated the same

Overview

When this has been going for a while, you'll have multiple parallel features and multiple concurrent Releases:

FAQs

Why are we deleting branches?

On a long running project the list of Feature- and Release branches can become huge. This can make tab-completion and branch differentiation more difficult.

When merged branches are deleted, it then becomes clear that existant branches are only those being actively being worked on

What if I want to trace the branch's history?

Remember that a branch is just a label for a specific commit. When you git checkout a specific branch, all you're checking out the commit that that branch name is assigned to.

Deleting a branch doesn't actually delete the history associated with it. If you check the history (using git log --graph, gtk, or PHPStorm's VCS log), you'll see where it was forked from its parent, the commits that happened, and where it was merged back in.

Can I keep my branches locally?

Your local git repo nis your own and can contain whatever branches you like. Just remember to not push up your local branches to the remotes.

What if I've merged my features and now my Release has bugs?

If bugs are found in the release, either commit directly into the Release branch, or sub-branch from the Release:

1. Branch off the Release with git checkout -b Release-001/MAG-123-Bugfix-the-Release
2. git commit your bugfixing until you're satisfied it's sorted
3. git checkout your Release branch
4. get merge your Release-001/MAG-123-Bugfix-the-Release sub-branch
5. git branch -d your Release-001/MAG-123-Bugfix-the-Release sub-branch

What do I do if my Release is way too broken and I want remove a Feature from it?

If you've merged a few features into a Release and it's clear you're not going to quickly resolve the problems, it's time to abandon that Release

Because unpicking the commits merged from one particular branch is too cumbersome, you'll need to reinstate your Feature branches and create a new Release

1. Find the last commit that represents your feature and copy its commit hash
   • Remember that when you deleted the branch, all you did was delete the label - the branch itself remains in the reflog
   • You can find this tree structure using git log --branch, gitk, or PHPStorm's VCS log
2. git checkout <commit_hash> for the commit hash you want to reinstate
3. git checkout -b MAG-123-Original-Branch-Name, which will reassign the branch-name label to that commit
4. Repeat the above until the branch names for all branches are reinstated
5. git branch -D the Release branch you're abandoning
6. You can then create a new Release and merge in all but the problematic Feature