Overview
This document will provide information about the software development processes, both for local development as well as the branching, tagging and pipeline running for our CI / CD workflow. This will be a living document to be updated as processes evolve to suit our needs. The goal is to keep things as simple as possible for developers while maintaining security in and a high standard of software delivered.
GitHub Branching Strategy
Classic Gitflow
Gitflow is an alternative Git branching model that involves the use of feature branches and multiple primary branches. Under this model, developers create a feature branch and delay merging it to the main trunk branch until the feature is complete. These long-lived feature branches require more collaboration to merge and have a higher risk of deviating from the trunk branch. They can also introduce conflicting updates.
This workflow doesn’t add any new concepts or commands beyond what’s required for the Feature Branch Workflow. Instead, it assigns very specific roles to different branches and defines how and when they should interact. In addition to feature branches, it uses individual branches for preparing, maintaining, and recording releases. Also developers get to leverage all the benefits of the Feature Branch Workflow: pull requests, isolated experiments, and more efficient collaboration.
In addition, you may want to install a git-flow cli tool or create commands’ aliases.
Branching model
Our workflow uses two branches and tags to record the history of the project. The main branch stores the release history to the test environment, and the develop branch serves as an integration branch for features. Tags of the project store official releases history with proper versioning. Also, the presentation branch is used for the presentation environment and it is synced with the main branch.
Feature branches
Each new feature should reside in its own branch, which can be pushed to the central repository for backup/collaboration. But, instead of branching off of main, feature branches use develop as their parent branch. When the feature’s code and tests are complete, it gets merged back into develop. Developer starts working on code improvements, writing documentation, etc.
Feature branches are generally created off to the latest develop branch and should never interact directly with main.
Creating a feature branch with git (at this moment you may want to start creating aliases 🙂):
git checkout develop
git pull
git checkout -b feature/new_feature_name
When you’re done with the development on the feature and test code is implemented, the next step is to merge the feature/new_feature_name into develop in the GitLab and assign a person to review your code or ask someone for help by mentioning in the comments. Do not forget to mark your branch for deletion after successful merge and squash commits into one!
Encapsulating feature development also makes it possible to leverage pull requests, which are a way to initiate discussions around a branch. They give other developers the opportunity to sign off on a feature before it gets integrated into the official project. Or, if you get stuck in the middle of a feature, you can open a pull request asking for suggestions from your colleagues. The point is, pull requests make it incredibly easy for your team to comment on each other’s work.
Hotfix branches
Maintenance or “hotfix” branches are used to quickly patch production releases. Hotfix branches are a lot like release branches and feature branches except they're based on main instead of develop. This is the only branch that should fork directly off of main. As soon as the fix is complete, it should be merged into both main and develop (or the current release branch if fix has a medium or low priority), and main should be tagged with an updated version number.
When merging hotfix branches back into the main branch, the same procedure with the responsible person and reviewer has to be followed: deployment checklist, test prelive/live environments!
Having a dedicated line of development for bug fixes lets your team address issues without interrupting the rest of the workflow or waiting for the next release cycle. You can think of maintenance branches as ad hoc release branches that work directly with main. A hotfix branch can be created using the following methods:
git checkout main
git pull
git checkout -b hotfix/bug_name
Resolving conflicts
When many people are working on a project, conflicts may occasionally arise when merging the code of a new feature. If you follow the strategy described above for working with branches, the chance of unpredictable and complex conflicts is minimal. But can still happen in several cases: when merging many features into develop at once and merging hotfix branches into develop. As you will see, we won’t expect any other kind of conflicts in this strategy!
Let's look at conflict resolution in a simple example with several new features being worked on at the same time. We'll also see that this conflict resolution also works when we merge the hotfix branches.
You are working carefully with our branching strategy on a new Feature 3. Your co-workers just completed and merged Feature 1 and Feature 2 into develop, it is important that each feature was squashed into one commit in MR. For example, they developed small features using existing components and you had a bigger task on refactoring these components. You will probably have a conflict when you try to merge your changes into develop. To solve this problem and leave the Git history clean, you need to apply rebasing. In short, this functionality allows you to apply missed commits incrementally on top of your code. You can do it using following commands:
git checkout develop
git pull
git checkout feature/your-feature-name
git rebase develop
To resolve the conflict when merging hotfix branches, you just need to change the last checkout command with your hotfix branch name.
After executing these commands in our example, you had to resolve the merge conflicts from Feature 1, then from Feature 2 (or vica-versa, if Feature 2 was merged before Feature 1). Git will add merge commits into your branch history and then you can merge Feature 3 into develop without any conflicts! Moreover, our git history remains clean and easy to revert in extreme situations.