Coding Standards Rollout Tool: Problem Background
As developers, we often inherit legacy codebases that lack consistent coding standards. In most languages we tend to have good tools to fix them in an automated way, freeing code reviewers up to focus on more substantive issues. However, rolling out coding standards changes needs careful management when a project is under active development. Widespread changes to all files may put ongoing feature development branches in a state of merge conflict. As part of a process moving towards coding standards checks/fixing built into the CI/CD pipeline, one step is to roll out changes to all files except those currently being worked on. As a contractor, I have done this a few times, and it has now reached the point where I have automated a solutioun to this problem and open sourced it. Let me introduce the Coding Standards Rollout Tool, and the process around it. Together, they provide a solution designed to ease the transition to modern coding standards in large projects while minimising disruption to ongoing development.
## A Plan for Fixing Your Coding Standards
What the Tool Does
This tool is specifically designed to apply coding standards across your entire project without interfering with files currently being worked on in feature branches. By doing so, it prevents merge conflicts and ensures that your codebase gradually evolves towards the desired standards.
Suggested Process for Introducing Coding Standards
- Clean Up: Remove obsolete branches to minimise edited files.
- Initial Run: Execute the tool to apply standards to all files except those which are edited in a branch.
- Merge Quickly: Merge quickly before significant changes are made in other branches.
- Continuous Updates: Encourage developers to update their branches. Rebasing now prevents conflicts later.
- Repeat: Run the tool periodically to capture stragglers.
- Automate: Integrate a coding standards fixer into your CI/CD pipeline once you feel it’s time.
Key Features
- Non-Disruptive Rollout: Changes are applied to files not currently modified in any branch, ensuring minimal disruption.
- Configurable: Compatible with any coding standards tool that can be executed through a shell command.
- Repeatable Process: Designed to be run multiple times, gradually enforcing standards as feature branches merge and close.
How to Use
- Configuration: Set up your configuration file (example provided in the repository).
- Build: Compile the tool using
make build
. - Execute: Run the binary with the appropriate config file.
For detailed instructions and configuration examples, visit the GitHub repository.
Behind the Scenes: Building the Tool
Creating the Coding Standards Rollout Tool was a rewarding challenge. Although primarily designed for PHP codebases, I
chose to write it in Go due to its performance and concurrency capabilities. The tool employs a worker pool approach to
efficiently handle multiple tasks in parallel, allowing it to process a repository with 200 open branches in about 5
seconds. It is doing a git diff
on a number of branches in parallel.
Test-driven development was integral to the process, ensuring robust and reliable code. By using spies as test doubles to represent Git system calls, I could test the business logic without side-effects. This methodical approach not only sped up development but also enhanced the tool’s reliability and performance.
Explore the repository to see the code, and feel free to contribute. Happy coding!
Conclusion
The Coding Standards Rollout Tool helps make your legacy more legible, without the disruption. By systematically applying coding standards, you can improve readability without getting told off for giving everybody merge conflicts. The process behind the tool gives you a path to getting coding standards fixing into the build pipeline. This can be done following the path of least disruption. Feel free to give it a try, and take a significant step towards a cleaner, more manageable codebase.