Intro
I’ve worked on multiple projects and with various people and I’ve seen quite a few Gitflow workflows in my day.
Over time, I started noticing that when working with Gitflow, I would need to check exactly how I should be deploying changes on every single project.
If you juggle multiple projects as I do, it can get confusing. Before you know it, you may find yourself following an incorrect flow. And that really sucks.
Learn From My Experience
However, this unpleasant experience has helped me find that one flow.
Lucky for me, I am currently in a position where I’m free to decide which flow my team and I are going to use in our projects.
This simplifies the process as we can standardize and document this approach so everyone can access it at any moment.
In this article, I’m going to be sharing my hard-acquired wisdom with you so that you can learn from my mistakes. Ready?
Research and Naming Conventions for Branches
This was not something I came up with all by myself.
To get things going, I’ve arranged a meeting with my team of developers. I’ve presented my initial solution and asked for feedback.
We’ve discussed some cases, cons, and pros and came out with a solution that satisfied all of us.
- Before the first commercial release (‘develop’ is the main branch)
- After the first commercial release (‘main’ is the main branch)
Before the release, the flow is very simple and shouldn’t cause any issues. So far, there’s just the ‘develop’ branch into which everything is merged. This branch should be the only branch except for the feature branches.
Okay, so let’s forget about the ‘develop’ branch for now. All we need to know is that all of the branches have to be based on the ‘develop’ and every PR has to be merged into it.
Unless you are working on some big feature that you are creating from multiple smaller branches (as it’s easier to check the code if there are only a few files), the feature branch itself has to be merged into ‘develop’. We are following the naming convention of branches based on the result:
- feature/name-of-the-feature – the directory with new features/things that are added to our application
- fix/fix-name – directory that contains the fixes for defects that we’ve found in our previous functionality
The names should be short and descriptive – they can contain stuff like the task name (short version) and ID. If you are using only the ID it’s not very descriptive so it might be hard to guess what you’ve done on this branch.
Create a Pull Request
After you’ve finished writing your code, create a PR (don’t merge anything into the ‘develop’ branch).
Since we are using Vercel or Netlify for all of our projects (at least at the beginning of the development process) creating a PR should create a preview URL.
You should test the results on the development environment as it can use different databases and behave differently than your local version.
Code Review Is a Must
Make sure to check your code by yourself and then let someone responsible for the code quality know that they should check your code too.
Once your PR’s been reviewed, go ahead and merge it into the ‘develop’ branch. If we’re talking about the time before the first release, then that’s all there is to it. Pretty simple, right?
You can learn more about code reviewing in this article.
Pushing Changes on a Timeline
Say you’ve prepared a release. If you push out something that breaks functionality or some visual components, it may cost you and your company a lot of money, reputation, and nerves.
Right now there are 2 paths that we can follow:
- You’re closely following a pre-imposed plan and are working on a schedule.
- Your client might change his mind quite often and you have more flexibility in terms of the timeline.
When considering the first option, we can introduce 2 new branch types:
- release/1.0.0 – should contain all changes from iterations that were planned to be released in the next version.
- hotfix/name – used to fix bugs that have to be released ASAP
The ‘release‘ branch should be created right after each release and should group all the new features for the next iteration. It’s created from the ‘main‘ branch but is merged into ‘main‘ and ‘develop‘.
For example, if you have a production release and the version is 1.0.0., once you will have upgraded it, the next release is going to be 1.1.0
All feature branches should be based either on this branch or the ‘main‘ branch. The ‘release‘ branch should be as similar to the production one as possible.
Each push into the ‘release’ branch should trigger a preview update to test with production-like data. Feel free to plan multiple parallel releases as they will not collide with each other.
These releases can be handled by different teams right until one of them is merged. That’s when you might have to fix conflicts that may have appeared in the process.
You may also want to add some kind of automation tool to update the version in ‘package.json‘ bump the tag in Gitflow or update the changelog file.
It’s good to do it even without automation but it’s much easier to forget and miss.
After you’ve finished, simply merge the ‘release’ branch with the ‘master‘ and ‘develop‘ to make these 2 lines as close to each other as possible.
Pushing Changes Without a Timeline
If you’re dealing with poor project management or the client keeps changing his mind, you can use the ‘develop‘ as your release branch.
It’s not a perfect solution as everything that is merged into ‘develop‘ will be merged into production. You have to be more careful and do many more tests to make sure that there aren’t any obvious defects.
Right before the release you can create a ‘release’ branch from the ‘develop‘ branch and merge it as a typical ‘release’ branch.
The last type of branch is ‘hotfix’. That’s a fix that has to be done ASAP so that no functionality is broken. These are created from the ‘main’ branch, like ‘hotfix/user-logout-issue‘.
They should be handled similar to the release branches but they just contain a single change. In the case of hotfixes, we should bump the last number of a version, e.g. ‘1.2.2’ => ‘1.2.3’.
Summary
Surely, this isn’t a fix-all solution, as there will always be some special cases that have to be handled individually.
If these cases come up persistently, you’re going to have to add some notes to the documentation so that everyone can follow your way of handling them.
Of course, this flow is just a suggestion that you can follow and I am sure it’s not the one and only good flow – it’s simply something that has been working for me for quite some time now.
I hope this can be of some help to people outside of Pagepro, too! Good Luck!
