To keep track of how a project has been changing through time is key to provide a big picture of what things have been changing and why. After all, the business logic or the domain required those changes to be recorded. Read this to know why it is important to keep an eye on a project’s history.
Become a Git Historian
This is chapter 2 of a series of blog posts about some pieces of advice, tools, and tips you can consider when you arrive at a Rails project considered as Legacy.
In the previous chapter, we reviewed our project’s anatomy.
In this chapter, we are using Git and other tools related to it to find out more about our Rails Legacy System. But this time, it’s our project’s history turn.
First, I want us to understand ‘history‘ as:
“The whole series of past events connected with someone or something”.
When speaking about history in a Rails project, it’s really important to check how our project has changed through time to get an idea of why things have been modified. Some of those adjustments were maybe done based on business logic, or maybe the domain required those changes.
Maybe, other changes happened because someone followed a particular path —which is a normal thing if you consider that every project is different and that there are infinite factors that can affect it in a positive or in a negative way.
In Software Development, a legacy system is outdated computing software that is still in use. Share on XIn Software Development, a legacy system is outdated computing software that is still in use. That system still meets the needs it was originally designed for but doesn’t allow growth. What a legacy system does now for the project is all it will ever do. A legacy system’s older technology won’t allow it to interact with newer systems.
Git extras
To get a general summary of things about the project, like repo age, the number of commits, and who the people involved are we could use git-extras.
$ brew install git-extras
$ git summary
project : big_rails_jump
repo age : 7 years
active : 1167 days
commits : 23794
files : 4084
authors :
3392 Aaron Patterson 14.3%
2596 David Heinemeier Hansson 10.9%
2389 Yukihiro Matsumoto 10.0%
2091 Lenny Kravitz 8.8%
1017 Pedro Infante 4.3%
1011 Tania Muñoz 4.2%
986 Edwin Cruz 4.1%
870 Juan Carlos Ruiz 3.7%
857 Omar Vazquez 3.6%
773 Jonathan Tapia 3.2%
695 Alejandro Espinoza 2.9%
667 Heriberto Perez 2.8%
590 Jose David 2.5%
548 Samantha Bello 2.3%
430 Juan Escutia 1.8%
417 J Balvin 1.8%
309 Myles Kennedy 1.3%
296 Federico Crespo 1.2%
266 Dr Simi 1.1%
257 Tigger 1.1%
246 Emmanuel Delgado 1.0%
234 Victor Velazquez 1.0%
Here is another interesting feature from git-extras, let’s try git effort:
$ git effort --above 15 {src,lib}/*
Displays “effort” statistics. Currently, it shows just the number of commits per file, highlighting the parts with the most activity. The “active days” column is the total number of days when contributed modifications to this file were made.
git-extras has many interesting features that you can explore and use to get a better understanding of your project.
Git log
Ok, now let’s understand how change on single objects works with git log.
$ git log --patch --stat Gemfile
commit f6043a0c731de894f05328da79f04b9456931074
Author: Ozmar Ugarte <ozmmarr.ugarte@magmalabs.io>
Date: Mon May 9 15:08:33 2016 -0400
NPS delighted survey scheduling
This commit was made only for testing purposes.
---
Gemfile | 3 +++
1 file changed, 3 insertions(+)
diff --git a/Gemfile b/Gemfile
index bbecfdf79..9b1fa9332 100644
--- a/Gemfile
+++ b/Gemfile
@@ -142,6 +142,9 @@ gem 'has_scope', '~> 0.6.0.rc'
gem 'cocoon'
gem 'sailthru-client', '~> 4.0.1'
+#Delighted nps
+gem 'delighted'
+
# form object
gem 'virtus', '~> 1.0.3'
As you can see, it will show why a specific update was made. Or, maybe it will just trigger more questions. But, at least you will be closer to your main goal, which is “understand what was the purpose of those changes”.
Git History
Also, if you prefer the fancy way and see the timeline of a particular file, you can try git-history.
Now, let’s use git-history, which is like a visual time machine where you can visually review any change on a specific file and understand its timeline.
Check this example out.
Look for Documentation (we’re using Git as well)
As we look for documentation keep in mind and ask yourself the following:
- Is there any documentation at all?
- Is there good commentary on the code?
- Do the names of things make sense?
- Are the System Use Cases documented?
- Is there someone in the team that understands the system?
We can use git whatchange doc to see logs and differences in our documentation, check the example above:
$ git whatchanged doc
commit e43e0fecfb5914ec0e72eadff73e90c0e14c7026
Author: Daniel Contreras <daniel.country.club@magmalabs.io>
Date: Thu Jan 28 19:32:35 2016 -0500
Render diagram inline. Use AsciiDoc for the table of contents.
:100644 100644 13fa6c9d4 ff7935d08 R055 doc/client-system/README.md doc/client-system/README.adoc
It seems that we have a doc folder. 🎉🎉🎉 It also seems like the last time a document was modified was in 2016, so it’s time to start documenting your new progress. That would help you in the future, and any other developer that joins the team.
Extra: The README
There is a README? Well, yes. But it is so poor…
Hey, but don’t worry, there are many templates you can use; like this example.
Wrap up
Here are more things to keep in mind:
- Document everything you learn.
- Keep documentation close to the code, simple is better.
- You must understand the design/architecture.
- Once you understand something, refine its documentation.
I hope you find this blogpost compelling. In the following chapter, we are going to cover some nice toolings for static analysis of your code.
