Comprehensive Git Workflow: From Branch Creation to Production Deployment

Comprehensive Git Workflow.md

Comprehensive Git Workflow: From Branch Creation to Production Deployment

This document outlines the updated Git workflow, with structured guidelines, reference links, and a table-based approach for managing branches, tagging releases, and deploying to production.

---

Branch Workflow Overview

Branch Type	Branch Naming	Created From	Merge Flow	Purpose
Feature	feature/<name>	master	alpha → develop → release → master	New feature development.
Bugfix	bugfix/<description>	master	alpha → develop → release → master	Fixing non-critical bugs.
Experiment	experiment/<name>	master	alpha → develop → release → master	Trying experimental changes.
Hotfix	hotfix/<description>	master	release → master	Urgent production bug fixes.
Release Candidate	release/<version>	master	master	Preparing for production release.
Developer Testing	alpha	master	Sync from master; isolated from develop and master.	Internal developer testing.
UAT	develop	master	Sync from master; isolated from alpha and master.	User Acceptance Testing.
Documentation	docs/<area>	master/develop/alpha	Managed separately.	Updating project documentation.
CI/CD	ci/<purpose>	Major branches (master, develop, alpha)	Merge back to originating branch only.	Managing CI/CD scripts and processes.

---

Branch Lifecycle: Full Flow

Step	Command	Description
Create a branch	git checkout -b feature/<name>	All branches must be created from master.
Push the branch	git push origin feature/<name>	Push the branch to the remote repository.
Develop changes	git add . and git commit -m "Message"	Commit changes with messages that follow Commit Message Guidelines
Open Pull Request (PR)	Open PR to appropriate branch (alpha or develop)	Add reviewers, labels, and ensure CI/CD tests pass.
Merge to alpha or develop	Through PR approval	Ensure all reviews are complete and merge into alpha or develop based on branch purpose.
Sync alpha/develop from master	git fetch origin master && git merge origin/master	Periodically sync alpha and develop with master.
Prepare Release Branch	git checkout -b release/<version>	Release branches are created from master after UAT is complete.
Merge Release into master	git checkout master && git merge release/<version>	Finalize the release and deploy to production.
Tag Release	git checkout master && git tag -a v<version> -m "Release version <version>" -F release-notes.txt or on the version branch (e.g., v1)	Tags should be created on master or the relative version branch after the release is merged. The release note should be build to give proper nuence of what it is bringing to the table.
Push the tag	git push origin v<version>	Pushes the tag to the remote repository.
Deploy to Production	CI/CD Pipeline	Deploy the master branch to production through the CI/CD pipeline.
Cleanup	git branch -d <branch> && git push origin --delete <branch>	Delete merged branches after release.

---

Rules and Best Practices

Rule	Explanation
Release branches are created from master.	Ensures stable production-ready code for release preparation.
alpha never merges into develop or master.	Prevents unwanted features from reaching UAT or production.
develop never merges into alpha or master.	Keeps testing environments isolated from each other.
Major branches (alpha, develop, master) sync from master.	Use merge commands to maintain consistency.
Tags should never use short names.	Always use full and descriptive tags.
Add release notes when tagging versions.	Attach detailed context for each release to the tag description.
Follow semantic versioning.	Use proper versioning to ensure clarity and backward compatibility.
Use meaningful commit messages.	Make commits descriptive to simplify debugging and collaboration.

---

Tagging Releases

Scenario	Command	Description
Tagging latest release	git tag -a v1.2.0 -m "Release version 1.2.0" -F release-notes.txt	Tags the latest version on the master branch with detailed release notes from release-notes.txt.
Push the tag	git push origin v1.2.0	Pushes the tag to the remote repository.
Create major release branch	git checkout -b v1	Creates a branch for a major version (e.g., v1 for all 1.x.x releases).
Push the major release branch	git push origin v1	Pushes the major release branch for managing older releases.
Supporting older releases	git checkout v1 && git merge hotfix/specific-issue	Applies bug fixes or updates to older major release branches.
Tagging older releases	git tag -a v1.2.1 -m "Bug fix for version 1.2.1" -F release-notes.txt	Tags updates to an older major release branch with detailed release notes.

---

Semantic Versioning

Version Component	Description	Example
MAJOR	Increment for incompatible or breaking changes.	2.0.0
MINOR	Increment for new, backward-compatible features.	1.1.0
PATCH	Increment for backward-compatible bug fixes.	1.0.1
Pre-release	Specify alpha, beta, or RC versions before a final release.	1.0.0-alpha.1
Build Metadata	Append build information, e.g., commit hash, build number.	1.0.0+build.001

---

Syncing and Cleanup

Branch to Sync	Command	Description
Sync alpha	git checkout alpha && git merge origin/master	Always sync alpha with master.
Sync develop	git checkout develop && git merge origin/master	Always sync develop with master.
Cleanup branches	git branch -d <branch> && git push origin --delete <branch>	Deletes merged branches to keep the repository clean.