[Enterprise Git Workflow Best Practice] Use a Sub-Project Branch When Developing Large Features

In a large project team, when developing major features, we may assign a few people to form a sub-project team. From the perspective of the overall project, this temporary group is working on a single, independent feature as a whole. However, within the temporary project, each member has their own sub-feature development tasks. In this case, individual developers should not commit their code directly to the main development branch, such as develop . Instead, a sub-project branch should be created. Each team member commits their code to the sub-project branch first, and at a designated point in time, the sub-project branch is merged into the main development branch. Terminology Definitions feature branch: A Git branch created when developing a new feature. Normally, only one person commits to this branch. You can also think of it as a personal branch. It is often named feature/ or feature- sub-project branch: When developing a large feature, a sub-project team consisting of several developers is formed. In this case, a larger development branch can be created for this sub-project. This branch can span multiple sprints. The sub-project developers first commit their changes to the project branch, and at a certain point in time, the project branch is merged into the main branch. The project branch can be named feature/-. Mistakes We Made with Sub-Project Branch Before writing on this topic, I assumed the use of sub-project branch was self-evident. However, after our team encountered several issues while using sub-project branches, we considered abandoning them. This led to even more problems, making me truly understand the importance of sub-project branch. As expected, the most profound realizations often come through mistakes. Below are the reasons we abandoned project branches. However, these reasons actually stemmed from incorrect usage rather than inherent flaws in project branches. Therefore, I will list the problems we encountered, along with the real causes. Project branches made the code messy: We had different versions of components across different project branches. Real Cause: Excessive development branches led to code management chaos, especially when many branches remained unsynchronized for long periods, making the overall code structure complex. Frequent conflicts during merges: Every time we merged a project branch, we encountered numerous conflicts that were difficult to resolve. Sometimes, new bugs were introduced while resolving conflicts, such as accidentally deleting correct code. Real Cause: Long periods without synchronization caused excessive conflicts during merging, increasing the effort required to resolve them. The correct approach is to synchronize from the develop branch to the sub-project branch regularly. In reality, these issues were not intrinsic to project branches themselves. Necessity of Sub-Project Branch Below are the key reasons for using project branches and best practices for managing them properly. Check for conflicts before merging: Fix the conflicts on the PR before merging. Evaluate the testing process: Notify the testing team before merging and ensure they have enough time to conduct tests. Significantly reduce the difficulty of reverts: If a branch contains only a single change, it minimizes coupling issues with other functionalities. Run automated tests on the project branch: Write sanity tests specifically for the branch to ensure feature reliability before merging. The develop branch is used more widely than you think: The develop branch is not just for some engineers—others, including different engineering teams, may also rely on it. Even testers and product managers might use the develop branch. Conclusion Using project branches can maximize release stability, improve code traceability, enhance testing efficiency, and facilitate better team collaboration. Best Practices for Using Sub-Project Branch Daily synchronization: Keep merging the develop branch changes to Sub-project branch to avoid excessive conflicts. Keep sub-project branches short-lived: Sub-project branches should not exist for too long (no more than 3 sprints). Squash merges: Use squash & merge when merging code to make all commits in 1 commit. Cause from the perspective of the develop branch, this feature should have only one or a few commits. Keep it clean: Delete the sub-project branch after merging to prevent unnecessary future commits.

Mar 22, 2025 - 21:25

[Enterprise Git Workflow Best Practice] Use a Sub-Project Branch When Developing Large Features

In a large project team, when developing major features, we may assign a few people to form a sub-project team. From the perspective of the overall project, this temporary group is working on a single, independent feature as a whole. However, within the temporary project, each member has their own sub-feature development tasks.

In this case, individual developers should not commit their code directly to the main development branch, such as develop . Instead, a sub-project branch should be created. Each team member commits their code to the sub-project branch first, and at a designated point in time, the sub-project branch is merged into the main development branch.

Terminology Definitions

feature branch: A Git branch created when developing a new feature. Normally, only one person commits to this branch. You can also think of it as a personal branch. It is often named feature/ or feature-

sub-project branch: When developing a large feature, a sub-project team consisting of several developers is formed. In this case, a larger development branch can be created for this sub-project. This branch can span multiple sprints. The sub-project developers first commit their changes to the project branch, and at a certain point in time, the project branch is merged into the main branch. The project branch can be named feature/-.

Mistakes We Made with Sub-Project Branch

Before writing on this topic, I assumed the use of sub-project branch was self-evident. However, after our team encountered several issues while using sub-project branches, we considered abandoning them. This led to even more problems, making me truly understand the importance of sub-project branch. As expected, the most profound realizations often come through mistakes.

Below are the reasons we abandoned project branches. However, these reasons actually stemmed from incorrect usage rather than inherent flaws in project branches. Therefore, I will list the problems we encountered, along with the real causes.

Project branches made the code messy: We had different versions of components across different project branches.
- Real Cause: Excessive development branches led to code management chaos, especially when many branches remained unsynchronized for long periods, making the overall code structure complex.
Frequent conflicts during merges: Every time we merged a project branch, we encountered numerous conflicts that were difficult to resolve. Sometimes, new bugs were introduced while resolving conflicts, such as accidentally deleting correct code.
- Real Cause: Long periods without synchronization caused excessive conflicts during merging, increasing the effort required to resolve them. The correct approach is to synchronize from the develop branch to the sub-project branch regularly.

In reality, these issues were not intrinsic to project branches themselves.

Necessity of Sub-Project Branch

Below are the key reasons for using project branches and best practices for managing them properly.

Check for conflicts before merging: Fix the conflicts on the PR before merging.

Evaluate the testing process: Notify the testing team before merging and ensure they have enough time to conduct tests.

Significantly reduce the difficulty of reverts: If a branch contains only a single change, it minimizes coupling issues with other functionalities.

Run automated tests on the project branch: Write sanity tests specifically for the branch to ensure feature reliability before merging.

The develop branch is used more widely than you think: The develop branch is not just for some engineers—others, including different engineering teams, may also rely on it.

Even testers and product managers might use the develop branch.

Conclusion
Using project branches can maximize release stability, improve code traceability, enhance testing efficiency, and facilitate better team collaboration.

Best Practices for Using Sub-Project Branch

Daily synchronization: Keep merging the develop branch changes to Sub-project branch to avoid excessive conflicts.
Keep sub-project branches short-lived: Sub-project branches should not exist for too long (no more than 3 sprints).
Squash merges: Use squash & merge when merging code to make all commits in 1 commit. Cause from the perspective of the develop branch, this feature should have only one or a few commits.

Keep it clean: Delete the sub-project branch after merging to prevent unnecessary future commits.