Improving Processes with Boilerplates
Gaurav Gusain
January 10, 2022

What are the challenges we faced? 

Being a growing organization, we regularly add, update and check our processes that are followed in the organization. So recently in ColoredCow, we decided to do the same and check for any of the process that is not being followed, any area where a new process needs to be set up, or any challenge that is being faced due to any of the process.

After some inspection, we figure out that in some of the projects we don’t have a well-defined process and necessary checks for coding standards setup, which results in poor code quality and longer review cycles.

One such project is Employee Portal which is an Open Source project that we use as a playground for freshers and interns. This way we provide them learning by contributing as a team to a real-life project which is used by the organization. When asked by the team helps in this training we got to learn about many problems that they were facing in the code reviews like:
1. Lack of details in Issues and Pull Request descriptions

2. Feedbacks on writing cleaner code

3. Multiple iterations of reviews

Though we have a defined process and guidelines for all these things it was really necessary to make everyone implement them.

So, how to make everyone follow the process?

In ColoredCow, enforcing a process is the last option we choose instead we try to make everyone understand the need of that process and how it will help everyone if we all follow it. Every member should feel responsible to follow the process as we all share the same organizational goal and works really hard as a team to achieve it.

So to make it easy for everyone to follow the process, we came to a solution of implementing the CI checks in the projects and making GitHub issues and PR templates. This helps in providing a structured framework for the code review cycle and also reduces the time and frustration of the reviewer and the developer.

Now, implementing these checks and templates in any existing project is a time-consuming task as we need to do a full project cleanup and if required we also need to communicate with the clients about it. Fortunately, in most of our projects, these CI checks are already applied. Only a few projects were there where we need to correct the process. So we started implementing these checks in the project so that all the projects should be in sync regarding the process.

But implementing these processes in the exiting projects is not a permanent solution. After discussing this problem and solution we came to a conclusion that we need to correct it at the initial phase i.e while a project is being set up. For this, we decided to make a boilerplate for frameworks that we usually use in our projects and provide all necessary coding standard checks, and template inbuilt in it. This way we will not enforce everyone to follow the process but the process will automatically be followed once everyone knows the purpose of these boilerplates and will use them for new projects. 

How do we work on the solution?

We decide to create a boilerplate for all the frameworks that we use, starting with Laravel as it is one of the frameworks that we are using for a long time. So we launched an open-source boilerplate for Laravel projects a few weeks ago and are using it for all of our new projects. It comes with some inbuilt feature that helps in automated code analysis before the review cycle

  1. Linting files via pre-commit and Larastan static code analyzer. Here’s the analyzer file. Read more about pre-commit in detail in this blog.
  1. GitHub workflow to automatically check Pull Requests when code is pushed
  2. GitHub templates that provide a basic structure for the PR and issue descriptions.
  3. One-liner command to set up the project from scratch with all the lining checks.

How is it helping now?

  • The measured time before this boilerplate with all the setups and Linting checks was around 30-40min. Now, it gets reduced to 5-10min.
  • A developer if now tries to push a code failing some basic coding standards, the system doesn’t allow it to do so.
  • The GitHub shows a red alert if any of the CI checks are failing, which gives developers a detailed view of what they are missing
  • No code without a green tick is allowed to merge.
  • Code Reviews seem to be smooth. Now, the reviewer’s prime focus while reviewing the code would be only to learn from the perspective of a developer while solving a problem.
  • The boilerplate is open source, hence can be used by any development community.

Future prospects

As we talk about the boilerplate, we are getting a lot of ideas of how we can make it more effective, some of the possible areas are:

  • Dockerization: Why we should use docker, here it is in their blog. Why docker in boilerplate, here’s the explanation – It’s obvious that a developer might be working on different applications and there would be various OS-specific dependencies, for Laravel like PHP, MySQL, Node, and Composer versions. These dependencies may be different for different applications. Changing the OS-specific dependency setup for a project may cause conflict with the existing applications, which would be a lot of effort-consuming. Hence isolating the Laravel project in a container would be for the greater good.
  • More such boilerplates: Currently we also have a basic boilerplate for WordPress and React Native. After Laravel we’ve decided to implement these CI checks and templates in these as well. There are many more frameworks like Flask, Django, etc. that are on our list. So, this way we are planning to make a well-defined process for project initiation in ColoredCow.