5 Steps to Take Over an Existing Ruby on Rails Project


When a Team starts working on a Rails Project that was written by another company it always requires increased mental strain from each member of the Team. And it is vital to have a strict plan to take all the systems under control. Rubyroid Labs aggregated the main steps one needs to follow to finish to take over a Project successfully.

1. Understand high-level functionality

It is the most valuable part and you definitely should start with it. To accomplish it, you might need to talk to the previous development Company/Team or to the Project Owner long before you will get your hands down to the code trying to refactor or adjust it.

Do not try to spare a couple of hours avoiding this easy task – it will pay off in the future. Here are some questions that will help you to understand the Project and its future:

  1. What business problem is solved with the help of the Project?
  2. Who is the main User of the Application?
  3. What are the main workflows?
  4. What is the history of the Project in short?

Feel free to ask about anything you do not feel confident about. Once this step is finished – you got a great power. You can look at the Project from the business point of view and you can offer/predict/discuss future needs/features of the Project from both technical and business sides.

2. Understand the model layer

All the Projects have several very intuitive model names like User, City, etc. But the problem is that some models are always named absolutely unintuitive to say nothing that code style might leave much to be desired.

What will you think about the model named SourceDestinationGroup (real example)? You will have troubles understanding the data in the model and, as a result, troubles with a big part of the Application.

To overcome this obstacle we often use gem named rails-erd. This tool allows us generating a nice image with all the models, their attributes and relations. Visual representation saves us tons of time and we can understand the situation quickly.

It is very easy to setup – here is the instruction. As a result, you will get an image like that:


Now you can look at a single image instead of 10 different models while reading the logic.

Keep in mind that rails-erd is highly customizable. One day you will find way too many objects in the image. You can easily restrict what models should be rendered to reduce the number of objects. Maybe you need just a high-level sight? Simply disable attributes rendering and you will have more space for models and relations. Experiment with rails-erd and you will get the desired view of the model layer.

3. Understand views

If you understand the model layer – your next step is to understand what way data are converted to views. Here you have two major options:

  1. It is a single page Application with AngularJS/ReactJS/EmberJS of the frontend and Rails as API on the backend.
  2. It is a usual Rails Application, which serves dynamic views.

In the first case, you will not have many troubles to figure out where the data came from. Developer Tools and JS framework specific extension like Batarang will help you. This way you can check all the AJAX requests for data and view structure.

In the second case, you might have troubles with too deep nesting of the views. Just imagine that a single page might have a dozen levels of partials nesting. You will have hard times searching for each button or header until you get used to views structure.

To make these searches easier we use gem xray-rails. It adds an awesome functionality to Application JS code. As a result, you can press ctrl+shift+x to highlight each partial on the page. Here is the result you will get:

This way you can easily understand which partial encloses specific tag or part of the page.

4. Check codebase quality

It is very important to know the quality of the codebase you got. If the quality is poor – notify the owner of the Project in advance, highlight parts of the Project and features, which are difficult to maintain. Make sure you took into consideration these pitfalls when you plan the schedule for new features development.

Luckily, with Ruby on Rails you can find a gem almost for anything.

To measure the codebase quality we use gem rubycritic. In fact, it leverages popular gems Reek, Flay and Flog under the hood and allows seeing various metrics like churn, complexity, duplication. Here are the report examples:

3 4 5

The best thing here is that all the reports are human readable. Reek, Flay and Flog gems did the main part of work, but their results are fine only for developers. On the other hand, rubycritic aggregates all the metrics and gives you a nice report, which can be used to show the situation on the Project to the owner.

5. Check security issues

Always take a look at the security issues since security holes might break the whole Application and lead to huge losses.

There are two nice tools to check possible security issues in the Application automatically. First one is bundler-audit. That gem will check your Gemfile and notify you if any of the gem version has known security vulnerabilities. As a result, you will get advisory information like that:


The second tool is named brakeman. It is a static analysis tool that checks your Rails code for a large amount of common mistakes. As a result, you get a nice HTML report:


Using this report you can easily fix critical and minor issues without any need to check the code by your own. Of course, no tool will guarantee you the reliability of the Application but it is better to fix common mistakes ASAP especially because they are common and widely known.


Every time you have to take care of the Project, which was written by another company just follow the steps above and make sure you understand each part of the Application logic and structure. Once that is done, you will be able to cope with any upcoming problem and efficiently react to new requirements.

Good Luck!


Green banner

Yury Kaliada

CTO at Rubyroid Labs

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *