🪵 Git Branching Strategy

Swift Signals follows a structured and scalable Git branching model tailored for a microservices architecture and continuous integration.

---

📌 Summary of Flow

graph TD
  A[feature/*] --> B[microservice/*]
  B --> C[dev]
  C --> D[main]
  E[hotfix] <--> D
  E <--> C

---

🌳 Permanent Branches

We maintain the following long-lived branches:

🔵 main

• This is the production-ready branch.
• All code here must pass all integration and system tests.
• Deployments are made from this branch.

🟠 dev

• This is the integration branch.
• Used to test the system as a whole before promoting changes to main.

🧩 Microservice Branches

Each microservice has its own permanent branch:

• user-service
• api-gateway
• optimisation-service
• simulation-service
• controller-service
• metric-service
• frontend

These branches allow teams to work independently on their respective domains.

---

🌱 Feature Branches

• Developers create short-lived feature branches off of their respective microservice branches:

  git checkout -b feature/auth-endpoint user-service
  

• Once complete:
  • The feature is merged back into the respective microservice branch.
  • The feature branch is deleted.

---

🔁 Merging Flow

1. After merging a feature into a microservice branch:

• Pull the latest changes from dev into the microservice branch:

git pull origin dev

• Resolve any conflicts within the microservice branch.
• Push the updated microservice branch to dev via a pull request.

2. From dev to main, a release candidate is created and promoted after successful testing.

---

✅ CI/CD Integration

GitHub Actions handles automated testing and validation at each stage of our workflow to ensure quality and stability.

Merge Direction	Test Type	Requirement
feature/* → microservice	Unit / Service Tests	✅ Must pass
microservice → dev	Integration Tests	✅ Must pass
dev → main	System / End-to-End Tests	✅ Must pass

🧪 Test Enforcement

• Each microservice has its own GitHub Actions workflow that triggers on pull requests.
• If any tests fail, the merge is blocked automatically.
• Integration tests validate interactions across services once code reaches dev.
• System-level tests verify the application as a whole before promoting to main.

⚠️ Note: All tests must complete successfully at each level before proceeding to the next. If any tests fail, the merge is blocked.

---

🛠️ Hotfixes

• A hotfix branch is created when urgent fixes are needed in production.
• Typically, it branches off from main:

  git checkout -b hotfix/fix-name main
  

• Apply the fix, then merge back into:
  • main ✅
  • dev ✅ (to keep environments in sync)

💡 Note: If the issue affects unreleased code, consider branching from dev instead.

---

🖼️ Example of Git Branching Strategy Diagram

gitGraph
   commit id: "Initial commit"
   commit id: "v1.0 Release"
   branch dev
   commit id: "Integration setup"

   branch user-service
   checkout user-service
   commit id: "User service base"
   branch feature/user-auth
   commit id: "Add login endpoint"
   checkout user-service
   merge feature/user-auth
   commit id: "Merged login feature"

   checkout dev
   merge user-service
   commit id: "Merged user-service into dev"

   branch simulation-service
   checkout simulation-service
   commit id: "Sim base"
   branch feature/sim-ui
   commit id: "Add UI sync"
   checkout simulation-service
   merge feature/sim-ui
   commit id: "Merged sim feature"

   checkout dev
   merge simulation-service
   commit id: "Merged sim into dev"

   checkout main
   merge dev
   commit id: "Production release"

   branch hotfix/fix-auth
   checkout hotfix/fix-auth
   commit id: "Fix auth bug"
   checkout main
   merge hotfix/fix-auth
   commit id: "Hotfix merged to main"
   checkout dev
   merge hotfix/fix-auth
   commit id: "Hotfix merged to dev"