Contribution 101

Repository Contribution Guide

Table of Contents

1. Git Flow
   • Main Branches
   • Release Branches
   • Working with Feature and Hotfix Branches
   • Commit Message Format
   • Task Workflow
   • Testing
   • Recommendations for the dev Branch
   • Advantages
2. Trunk Based Development
   • Main Branches
   • Working with Feature and Hotfix Branches
   • Commit Message Format
   • Task Workflow
   • Testing
   • Advantages of Trunk Based Development
3. Comparison of Git Flow and Trunk Based Development
4. Task Status Transitions and Best Practices
5. Analysis of the Two Approaches
6. Feasibility of Using Both Approaches for Two Teams
7. Recommendations for Implementation
8. Conclusion

---

Git Flow

Main Branches

• main: the main branch containing stable production-ready code.
• dev: the branch for integrating changes intended for the next release.
• test: the branch for testing release changes.

Release Branches

• release/*: branches intended for preparing and testing releases.
  • Example: release/generic:v1.0.0 for a general release or release/somePartnerAlt1:v1.0.1 for a partner-specific release.
• After completion, the release branch is merged into main and dev.

main
  |
  |----------> release/* ----------> main
  |              |
  |              |
  |              v
  |----------> test ---------------> main
  |              ^
  |              |
  |----------> dev ----------------> release/*
                 ^
                 |
                 |---------------------> feat/* or hotfix/*

Working with Feature and Hotfix Branches

1. Creating a New Branch:

   • For developing a new feature or fix, create a branch from dev:

     git checkout -b feat/yourFeatureName dev

2. Regular Updates from dev:

   • Regularly synchronize your branch with the latest state of dev:

     git pull origin dev

   • This minimizes the risk of conflicts during merging.

3. Sync Before Creating a Pull Request:

   • Ensure your branch is fully synchronized with dev before creating a Pull Request:

     git pull origin dev
     git push origin feat/yourFeatureName

4. Creating a Pull Request:

   • After completing your work, create a Pull Request to the appropriate release branch (e.g., release/generic:v1.0.0).

Commit Message Format

• For Adding New Features:

  feat: brief description of the added feature
  
  detailed description of changes
  

• For Fixing Bugs:

  fix: brief description of the fix
  
  detailed description of changes
  

Task Workflow

1. Task Statuses:

   • backlog: the task is in the backlog.
   • todo: the task is ready to start.
   • in progress: the task is in progress (a branch is created, e.g., feat/someNewFunc).
   • testing: the task is being tested (testing is performed on the feature branch).
   • rework: the task is returned for rework after failed testing.
   • code review: the task is under code review before merging.
   • pre-deploy: the task undergoes smoke testing on the release branch.
   • done: the task is completed, and changes are merged into main.

2. Step-by-Step Process:

   • Step 1: Move the task from backlog to todo.
   • Step 2: Move the task to in progress and create a branch:

     git checkout -b feat/someNewFunc dev

   • Step 3: Regularly update your branch:

     git pull origin dev

   • Step 4: After completing the work, move the task to testing and test the changes on the feature branch.
   • Step 5: If testing fails, move the task to rework and make the necessary fixes.
   • Step 6: After successful testing, create a Pull Request to the release branch and move the task to code review.
   • Step 7: After successful code review, move the task to pre-deploy and perform smoke testing on the test branch.
   • Step 8: After successful testing, merge the changes into dev and main, and move the task to done.

Testing

1. Testing on the Feature Branch:
   • All changes must be tested on the feature branch before creating a Pull Request.
2. Smoke Testing:
   • After merging changes into the release branch, perform smoke testing on the test branch.

---

Recommendations for the dev Branch

1. Regular Updates from dev:

   • Regularly pull changes from the dev branch during development:

     git pull origin dev

   • This ensures your branch remains up-to-date and reduces the likelihood of conflicts.

2. Example Workflow:

   • Create a new branch for development:

     git checkout -b feat/addNewButton dev

   • Regularly update your branch:

     git pull origin dev

   • Before creating a Pull Request, ensure synchronization:

     git pull origin dev
     git push origin feat/addNewButton

---

Advantages

• Regular updates from dev help avoid merge conflicts.
• Using release branches simplifies release management and testing.
• A clear task workflow ensures transparency and predictability in development.
• This document standardizes the workflow, ensuring consistency across the team.

---

Trunk Based Development

Main Branches

• main: the single main branch containing stable production-ready code.
• dev: the branch for integrating changes, used by developers for preliminary functionality checks.
• test: the branch for testing changes, used by testers before merging into main.
• feature/*: short-lived branches for developing new features or fixes.

Note: In the original Trunk Based Development (TBD) methodology, only the main branch and short-lived feature branches are used. The inclusion of dev and test branches in this guide is an adaptation to provide additional flexibility for testing and staging changes.

main
  |
  |--------> test --------------> main
  |            ^
  |            |
  |--------> dev ---------------> test
               ^
               |
               |---------> feature/*

Working with Feature and Hotfix Branches

1. Creating a New Branch:

   • For developing a new feature or fix, create a short-lived branch from dev:

     git checkout -b feature/yourFeatureName dev

2. Regular Updates from dev:

   • Regularly synchronize your branch with the latest state of dev:

     git pull origin dev

   • This minimizes the risk of conflicts during merging.

3. Merging into dev:

   • After completing your work, create a Pull Request to the dev branch for preliminary review.

4. Testing in test:

   • After successful merging into dev, test the changes on the test branch. Create a Pull Request from dev to test:

     git checkout test
     git merge dev
     git push origin test

5. Merging into main:

   • After successful testing, merge the changes into main:

     git checkout main
     git merge test
     git push origin main

6. Deleting the Branch:

   • After merging the Pull Request, delete the short-lived branch:

     git branch -d feature/yourFeatureName
     git push origin --delete feature/yourFeatureName

Commit Message Format

• For Adding New Features:

  feat: brief description of the added feature
  
  detailed description of changes
  

• For Fixing Bugs:

  fix: brief description of the fix
  
  detailed description of changes
  

Task Workflow

1. Task Statuses:

   • backlog: the task is in the backlog.
   • todo: the task is ready to start.
   • in progress: the task is in progress (a branch is created, e.g., feature/someNewFunc).
   • testing: the task is being tested on the test branch.
   • rework: the task is returned for rework after failed testing.
   • code review: the task is under code review before merging.
   • done: the task is completed, and changes are merged into main.

2. Step-by-Step Process:

   • Step 1: Move the task from backlog to todo.
   • Step 2: Move the task to in progress and create a branch:

     git checkout -b feature/someNewFunc dev

   • Step 3: Regularly update your branch:

     git pull origin dev

   • Step 4: After completing the work, move the task to testing and test the changes on the test branch.
   • Step 5: If testing fails, move the task to rework and make the necessary fixes.
   • Step 6: After successful testing, create a Pull Request to the main branch and move the task to code review.
   • Step 7: After successful code review, merge the changes into main, and move the task to done.

Testing

1. Testing on the Feature Branch:
   • All changes must be tested on the feature branch before creating a Pull Request.
2. Testing on the test Branch:
   • After merging changes into dev, perform testing on the test branch.
3. Integration Testing:
   • After merging changes into main, perform integration testing.

---

Advantages of Trunk Based Development with Test and Development Branches

• Change Isolation: Developers and testers work in separate branches, not affecting main.
• Flexibility: Allows testing changes before they reach production.
• CI/CD Compatibility: Changes go through multiple verification stages, reducing the risk of production errors.
• Feature Toggles (Flags): Use feature toggles to enable or disable features in production without requiring code changes or deployments.
• Branch by Abstraction: Implement changes incrementally by abstracting new functionality behind interfaces, reducing the need for long-lived branches.
• Continuous Code Review: Encourage frequent and incremental code reviews to maintain code quality and ensure faster feedback loops.

---

Comparison of Git Flow and Trunk Based Development

Git Flow

Pros:

1. Clear Branch Structure:
   • Suitable for projects with long development cycles.
   • Release branches isolate release preparation from main development.
2. Convenient for Large Teams:
   • Developers can work on multiple features and releases simultaneously.
3. Quality Control:
   • Testing on test and release/* branches reduces the likelihood of production errors.

Cons:

1. Complex Branch Management:
   • A large number of branches can complicate the process, especially for small teams.
2. Long Development Cycles:
   • Suitable for projects with infrequent releases but may be excessive for frequent updates.
3. Conflict Risk:
   • Long-lived branches increase the likelihood of merge conflicts.

---

Trunk Based Development

Pros:

1. Simple Structure:
   • Only main, dev, test, and short-lived branches are used, simplifying the process.
2. Fast Integration:
   • Changes quickly reach main, ideal for Continuous Integration/Continuous Deployment (CI/CD).
3. Conflict Minimization:
   • Short-lived branches and regular updates from dev or main reduce conflict risks.
4. Testing Flexibility:
   • The presence of dev and test branches allows isolating changes for developers and testers.

Cons:

1. Requires Discipline:
   • Regular branch updates and frequent merges require strict adherence to processes.
2. Less Release Isolation:
   • No dedicated branch for release preparation, which may be inconvenient for large projects.
3. Not Suitable for All Teams:
   • May be challenging for teams accustomed to long development cycles.

---

When to Use?

Criterion	Git Flow	Trunk Based Development
Team Size	Large teams	Small and medium teams
Release Frequency	Infrequent releases	Frequent releases
Project Complexity	Complex projects with long cycles	Simple or fast-evolving projects
CI/CD Support	Limited	Excellent
Release Isolation	High	Low
Branch Management	Complex	Simple

---

Recommendations

• Use Git Flow if your project has long development cycles, complex releases, or requires strict release isolation.
• Choose Trunk Based Development if you want to speed up development, release frequently, and actively use CI/CD.

---

Task Status Transitions and Best Practices

Git Flow

Task Status Transitions

1. backlog → todo:
   • The task is prioritized and ready to start.
2. todo → in progress:
   • A branch is created from dev (e.g., feat/someNewFunc).
3. in progress → testing:
   • The feature branch is tested locally or in a staging environment.
4. testing → rework:
   • If testing fails, the task is returned for fixes.
5. testing → code review:
   • After successful testing, a Pull Request is created to the release branch.
6. code review → pre-deploy:
   • After approval, the task undergoes smoke testing on the test branch.
7. pre-deploy → done:
   • After successful testing, changes are merged into main and dev.

Best Practices

• Branch Naming: Use clear and consistent branch names (e.g., feat/addLogin, hotfix/fixLoginBug).
• Regular Updates: Frequently pull changes from dev to avoid conflicts.
• Testing: Test thoroughly on feature branches before merging.
• Release Isolation: Use release branches to isolate changes for specific releases.
• Documentation: Document changes in Pull Requests for better traceability.

---

Trunk Based Development (TBD)

Task Status Transitions

1. backlog → todo:
   • The task is prioritized and ready to start.
2. todo → in progress:
   • A short-lived branch is created from dev (e.g., feature/someNewFunc).
3. in progress → testing:
   • The feature branch is tested locally or in a staging environment.
4. testing → rework:
   • If testing fails, the task is returned for fixes.
5. testing → code review:
   • After successful testing, a Pull Request is created to dev.
6. code review → done:
   • After approval, changes are merged into dev, tested on test, and finally merged into main.

Best Practices

• Short-Lived Branches: Keep branches short-lived to minimize conflicts.
• Frequent Merges: Merge changes into dev frequently to ensure fast feedback.
• Testing Stages: Use test for staging changes before merging into main.
• Feature Toggles: Use feature toggles to enable or disable features in production.
• Continuous Integration: Automate testing and integration to maintain code quality.

---

Comparison of Task Status Transitions

Status Transition	Git Flow	Trunk Based Development (TBD)
backlog → todo	Task is prioritized for release.	Task is prioritized for immediate work.
todo → in progress	Branch created from dev.	Short-lived branch created from dev.
in progress → testing	Tested on feature branch.	Tested on feature branch.
testing → rework	Fixes applied on feature branch.	Fixes applied on feature branch.
testing → code review	PR to release branch.	PR to dev.
code review → done	Merged into main and dev.	Merged into main via test.

---

Recommendations for Task Management

• Use Git Flow for projects with long development cycles and strict release isolation.
• Use TBD for projects with frequent releases and CI/CD pipelines.
• Ensure clear communication and documentation for all task transitions.
• Regularly review and refine workflows to adapt to team needs.

---

Analysis of the Two Approaches

Git Flow

Logical Consistency

1. The described workflow is logical and aligns with the standard Git Flow methodology.
2. The use of release/* branches for isolating release preparation ensures stability in main and dev.
3. Task status transitions are well-defined and follow a clear sequence.

Potential Issues

1. Complexity: Managing multiple long-lived branches (main, dev, test, release/*, feat/*, hotfix/*) can become overwhelming for smaller teams.
2. Merge Conflicts: Long-lived feature branches increase the risk of conflicts, especially if multiple developers work on overlapping areas of the codebase.

Suitability for a Team

1. Best suited for larger teams with structured release cycles and dedicated QA/testing teams.
2. Requires discipline in branch management and adherence to the workflow.

---

Trunk Based Development (TBD)

Logical Consistency

1. The workflow is consistent with the principles of TBD, emphasizing short-lived branches and frequent integration.
2. The use of dev and test branches provides flexibility for testing and staging changes before merging into main.

Potential Issues

1. Testing Bottleneck: If multiple features are merged into dev simultaneously, it may create bottlenecks during testing on the test branch.
2. Discipline Required: Developers must frequently merge changes and resolve conflicts promptly to avoid disruptions.

Suitability for a Team

1. Ideal for smaller or medium-sized teams with frequent releases and CI/CD pipelines.
2. Requires a strong culture of collaboration and continuous integration.

---

Feasibility of Using Both Approaches for Two Teams

Compatibility

1. Both approaches can coexist if the teams work on separate projects or modules with minimal interdependencies.
2. Clear communication and documentation are essential to avoid confusion when integrating changes across teams.

Challenges

1. Cross-Team Collaboration: If the two teams need to collaborate on shared code, differences in workflows (e.g., release branches in Git Flow vs. short-lived branches in TBD) may cause friction.
2. Tooling and Automation: CI/CD pipelines and testing frameworks must support both workflows to ensure smooth integration.

Implementation

1. Assign Git Flow to a team working on a project with long release cycles and complex dependencies.
2. Assign TBD to a team working on a fast-evolving project with frequent releases.
3. Establish clear guidelines for integrating changes between the two teams, such as using main as the common integration point.

---

Recommendations for Implementation

For Git Flow

1. Use for teams with structured release cycles and a need for strict release isolation.
2. Automate testing and deployment for release/* and test branches to reduce manual effort.

For TBD

1. Use for teams with frequent releases and a focus on CI/CD.
2. Encourage developers to merge changes into dev frequently and resolve conflicts promptly.

Cross-Team Integration

1. Define a shared branching strategy for integrating changes between the two teams.
2. Use feature toggles to manage incomplete features when integrating changes from TBD into Git Flow.

Monitoring and Feedback

1. Regularly review the workflows to identify bottlenecks or inefficiencies.
2. Gather feedback from both teams to refine the processes and address challenges.

---

Conclusion

Both approaches are logically sound and can work effectively for their respective use cases. However, successful implementation requires clear communication, strong discipline, and appropriate tooling. With proper planning and coordination, it is feasible to use Git Flow and TBD for two different teams.