[ en ] [ pt-BR ]
[ Intro ] [ Tool ] [ Branching Strategy ] [ Example Flows ] [ FAQ ] [ License ]
g-flow is a complete and practical Gitflow implementation.
Gitflow is a well known and widely adopted branching strategy.
There are, however, a few problems:
- The tools created by the author himself, not only seem to be abandoned, but don't take in consideraton the existence of a hub (Github, Gitlab, Bitbucket, etc...) what spawn a myriad of forks, which in turn have their own problems;
- The strategy itself and therefore the tools consider only two permanent branches, which not only doesn't match the reality of many repositories, but leaves room for improvement (more on that below).
As mentioned before g-flow is a strategy based on Gitflow, shown in the diagrams and concepts below.
Important points to be considered:
- Only these branches are permanent: Development (dev), Homologation (homolog), Production (main) and Release branches;
- Temporary branches are deleted after the launch of the release that contains them;
- All work branches always come from Production;
- The Production branch only receives updates from Hotfixes and Releases;
- Releases are walways launched on Production and Homologation.
- Development is the Bleeding Edge branch,where all issues are merged once approved.
- Homologation is the Pre-Release branch and can temporarily become out of sync with the others depending on the Homologation process.
- Release branches are permanent on purpose, so it's possible to do quick switches for regression, inspection, comparisons, etc...
- At the conception of the project (time === 0), the initial branches (Development, Homologation and Production) are exactly equal and, in case of a pre-existing system, a mirror of the Client's Production branch;
- Code Freeze is the period of time when it's absolutely forbidden to do merges in any branch.
- As in any Open Source Software, the
g-flow.sh
tool is provided without warranties (see the License file); - Please note that the tool will always:
- Switch to the Production branch and do a pull to certify that your production copy is synchronized;
- The immediate push of the created branch to remote.
- Although I'm not an ignorant on the subject I'm not, by any stretch of imagination, a bash programmer and therefore many things in the tool can probably be improved. Soon I'll publish the guidelines to contribute to the project.
- At the moment the tool was only tested on Linux (Fedora, but it probably works in any distribution that has a modern bash implementation running). Tests in other Linux distributions and other Operating Systems are more than welcome, but I can't guarantee implementations for difrerent Operating Systems.
Just clone this repository or download the most recent release.
Optionally (recommended) create a symbolic link to the tool:
sudo ln -s path_to_clone/bin/g-flow.sh /usr/local/bin/g-flow
Just run the tool with no arguments to display the usage help:
g-flow
The tool runs with a default configuration, present in the .g-flowrc.dist file.
To change any configuration copy this file as .g-flowrc
in your project's root path. The file is always valid only for the project itself.
Don't use quotes in any configuration values and don't use characters except for letters, numbers, dashes ( - ) and underscores ( _ ).
- After identifying the bug, the Release Manager (RM) declares the beginning of the Code Freeze.
- Dev creates the branch with the format hotfix/issue from Production and immediately creates it remotely, e.g.:
With g-flow.sh
:
g-flow hfix 1903
Without g-flow.sh
:
git checkout -b hotfix/1903 main
git push -u origin hotfix/1903
- Dev works on it's branch, tests the fix locally, makes pushes to it's remote branch and notifies the RM:
git add modified_files
git commit -m "Commit Message"
git push
- The RM merges it into Production and Development.
- Being declared that the bug is solved, the RM launches the Release from Production and merges it to all Homologation and Production branches.
- Code Freeze ends.
- Dev creates the branch with the format feature/issue from Production and immediately creates it remotely, e.g.:
With g-flow.sh
:
g-flow feat 1901
Without g-flow.sh
:
git checkout -b feature/1901 main
git push -u origin feature/1901
- Dev works on it’s branch, tests the feature locally, makes pushes to it’s remote branch:
git add modified_files
git commit -m "Commit Message"
git push
- After completing the work, Dev opens a PR to Development.
- Code Review is performed.
- If the PR is approved, the RM merges it into Development and Homologation and declares the beginning of the Code Freeze.
- In Homologation the Business Logic tests are performed. If the work is homologated, it's merged in the Client's Homologation environment.
- The Client then performs it's tests so the change is homologated.
- If the client homologates it, the RM launches the Release from Homologation and and merges it to all Homologation and Production branches.
- Code Freeze ends.
- A branch with the name following the format epic/epic_name is created from Production.
- Devs create feature branches with the name following the format feature/issue from the epic/epic_name branch and immediatelt create them remotely e.g.:
With g-flow.sh
:
g-flow feat 1902 epic/nome_epic
Without g-flow.sh
:
git checkout -b feature/1902 epic/nome_epic
git push -u origin feature/1902
- Devs work on their branches, test the feature locally and make pushes to their remote branch.
git add modified_files
git commit -m "Commit Message"
git push
- After completing the work, Dev opens a PR to the Epic's branch.
- Code Review is performed.
- If the PR is approved, the RM merges it into the Epic's branch.
- Once the epic is finished and tested, Dev opens a PR to Development.
- If the PR is approved, the RM merges it into Development and Homologation and declares the beginning of the Code Freeze.
- In Homologation the Business Logic tests are performed. If the work is homologated, it's merged in the Client's Homologation environment.
- The Client then performs it's tests so the change is homologated.
- If the client homologates it, the RM launches the Release from Homologation and and merges it to all Homologation and Production branches.
- Code Freeze ends.
- Dev creates the branch with the format fix/issue from Production and immediately creates it remotely, e.g.:
With g-flow.sh
:
g-flow fix 1901
Without g-flow.sh
:
git checkout -b fix/1901 main
git push -u origin fix/1901
- Dev works on it’s branch, tests the fix locally, makes pushes to it’s remote branch:
git add modified_files
git commit -m "Commit Message"
git push
- After completing the work, Dev opens a PR to Development.
- Code Review is performed.
- If the PR is approved, the RM merges it into Development and Homologation and declares the beginning of the Code Freeze.
- In Homologation the Business Logic tests are performed. If the work is homologated, it's merged in the Client's Homologation environment.
- The Client then performs it's tests so the change is homologated.
- If the client homologates it, the RM launches the Release from Homologation and and merges it to all Homologation and Production branches.
- Code Freeze ends.
1. There are so many branch types. Why?
So that is possible to build metricsw (amount of fixes, features, etc... per release).2. What's the difference between Hotfix and Fix?
The difference is procedural. Hotfix is a critical bug that is happening in Production and therefore must be fixed quickly, ignoring some steps that are performed in a "normal" Fix (Code Review, Source of the Release, etc...).3. What's the reason for the Homologation branch to receive releases if the release comes from it (same case with hotfixes and the Production branch)?
In order to keep the Homologation and Production branches absolutely synchronized, including releases and versioning.4. Versioning?
Yes. g-flow is aligned with the practice of [Semantic Verioning](https://semver.org/). The tool will include a "bump" script.Licensed as MIT 2023-* by Galvão Desenvolvimento Ltda.