Working in Parallel Branches in My Project: A Step-by-Step Journey

Introduction

Working on software projects can often feel like a delicate balancing act, especially when you're developing multiple features simultaneously. In this post, I'll walk you through the process of working in parallel branches in my project, sharing the challenges I faced, the lessons I learned, and the strategies I used to keep everything on track. You’ll get an inside look at how I managed branches, issues, and merges, and I'll link to the project repo and issues so you can see the work in action.

Setting Up Parallel Branches

In any project, there comes a time when you need to work on multiple features or fixes simultaneously. In my case, the project was EnglishFormatter, where I was developing two major features:

Adding support for processing multiple files and folders in the CLI tool.
Integrating API calls to process file content and handle output with robust error handling.

To prevent conflicts and ensure modular development, I created separate branches for each feature.

Main Branch: This branch held the stable version of the project. Every completed feature was merged here once it passed review and testing.
Feature Branches:
- Alpha03: Focused on integrating an API call that takes file content as input and returns a processed response. This feature was tracked in Issue #9.
- Alpha02: Added support for processing multiple files and folders in the CLI tool. This feature was tracked in Issue #7.

Each branch had its own isolated work environment, which allowed me to avoid conflicts and breakages in the main branch while I was working on these features.

Link to the project repository: EnglishFormatter GitHub Repository

Working on Features

1. API Integration

In the feature/api-integration branch, the goal was to build an API integration that could send file content to a processing service and handle the response. I used CURL to make the API call and handled JSON payloads using the nlohmann/json library. This feature was tracked in Issue #9.

Key steps included:

Reading content from a file.
Formatting that content into a JSON structure for the API.
Making a POST request to the API and receiving the response.
Parsing the response and saving the processed content into a new file.

You can check out the implementation of this feature in the commit here.

2. Add Support for Multiple Files and Folders

In parallel, I worked on Issue #7 in the feature/multi-file-support branch. The goal was to enhance the CLI tool so that it could accept multiple files and folder paths as input. The feature included:

Adding functionality to the CLI to accept and process multiple files or folders as arguments.
Recursively processing files within any provided folders.
Ensuring robust error handling if a file or folder path was invalid.

You can check out the implementation of this feature in the commit here.

The Merge Process

Once both features were in a stable state, it was time to merge them back into the main branch. Here’s how I approached it:

Syncing with the Main Branch: Before merging, I ensured my feature branches were up to date with the latest changes from the main branch. This involved pulling the latest commits from the main branch into each feature branch:

   git checkout Alpha03
   git pull origin main

Handling Conflicts: While most of my changes were isolated, I still encountered minor merge conflicts. For example, both branches modified the eng_format.cpp file, but in different parts. To resolve conflicts:
- I used git merge to bring both feature branches together.
- I carefully reviewed and resolved any conflicts by ensuring both the API integration and error handling were retained in the merged code.
Testing: After resolving the conflicts, I ran my test suite to ensure both features were working as expected. I tested:
- Successful API calls with proper file input.
- Error scenarios, such as missing environment variables or invalid API responses.
- Confirming that the program exited with proper codes in each scenario.
Pushing the Merge: Once testing was successful, I merged both feature branches into the main branch using:

   git checkout main
   git merge Alpha03
   git merge Alpha02
   git push origin main

Link to the merge commit for the multi-file support feature: Multi-File Support Merge Commit

Challenges Faced

1. Merge Conflicts

While working on two features that both touched the eng_format.cpp file, I encountered a few merge conflicts. Both branches had made changes to core functions like convert_file, but for different reasons. I learned that it’s crucial to communicate changes early, even with myself, by regularly committing smaller, logical changes and keeping feature branches up to date with main.

2. Testing Complex Scenarios

Simulating real-world failure conditions (like a downed API or missing environment variables) was challenging, but critical to the robustness of the error-handling feature. I created mock test cases to simulate different failure scenarios, which helped to ensure the program responded properly in all cases.

3. Managing Branches

Working with multiple branches simultaneously requires attention to detail. For instance, when switching between branches, I sometimes forgot to merge the latest updates from main, leading to unnecessary conflicts down the road. I’ve since developed the habit of pulling the latest changes from main into each feature branch regularly to minimize conflicts.

Lessons Learned

1. Communication and Consistency

Even when working solo, it’s important to document and plan changes clearly. I learned that writing down the goals of each feature and what files I expected to change made the merging process smoother.

2. Merge Early and Often

The earlier you resolve conflicts, the easier they are to manage. Pulling updates from the main branch frequently into my feature branches helped reduce merge conflicts, making the final merge much smoother.

3. Test Before and After

It’s tempting to merge code without thoroughly testing every scenario, but I learned that testing both before and after a merge prevents subtle bugs from creeping into the codebase.

What I Would Do Differently Next Time

Create Smaller, More Focused Branches: Instead of working on multiple large features at once, I’d break the work into smaller, more manageable chunks. This would help minimize merge conflicts and make it easier to test and review the code.
Use Feature Flags: Implementing feature flags could allow me to merge incomplete features into main without affecting the production code, enabling continuous integration and faster feedback loops.

Conclusion

Working with parallel branches was both challenging and rewarding. While managing multiple branches can sometimes feel overwhelming, the process taught me the importance of keeping branches up-to-date, testing thoroughly, and communicating changes effectively. Each feature added to the project helped make the codebase more robust, and I’m looking forward to applying these lessons in future projects.

Blog