A GitHub Code Archeology adventure

At work, I am part of a team which maintains the Enthought Tool Suite (ETS). ETS includes a number of open source Python packages which are the foundation of the desktop applications we build at work. One of those packages is enable, a 2D drawing library.

Yesterday, I came across this issue on enable regarding a python module (kiva.fonttools.sstruct) which wasn't used anywhere in the enable codebase at the moment. "... at the moment" is important here because the enable GitHub repository has been evolving for over 10 years now and we don't know if at some point in the past, kiva.fonttools.sstruct was used somewhere in enable. Before we decide on removing the python module from the codebase, we need to understand when it was added, who was using it and how and when the dependency on enable.fonttools.struct got removed from enable. Only then can we confidently remove the module without worrying about unexpected repurcussions.

So, I started digging.

The first thing to do is to look at the history of the module itself via the GitHub interface. We do that by clicking on the History button on the right.

Use the History button on the right.

 

That will now show us the history of the kiva.fonttools.sstruct Python module

The list of Git commits which modified the kiva.fonttools.sstruct python module.

 

The first commit which modified this module in this tree - which isn't actually the commit which created this module.

Click on the highlighted "<>" button to browse the GitHub repository at that commit.

Here we see the first issue. The first commit in the list of Git commits reported on GitHub is "move kiva out of enable namespace". But, if you look at that commit, you will notice that the commit simply moved `kiva.fonttools.sstruct` from one location to another. But, because we moved the module while making other significant changes in the codebase, Git wasn't able to keep the history of the kiva.fonttools.sstruct module intact.

To understand the history of kiva.fonttools.sstruct, we need to dig deeper. We can do that by looking at the Git history of the commit - 76683223b1d76d94b8557d41ea266c823153fa37. In that history, let's browse the GitHub repository and look for kiva.fonttools.sstruct in the commit c61bd1dcd993541020a90244fa8fe2d461255e99. 

Let's browse the GitHub repository at the selected commit.

This is where we run into the same problem again. When I find the kiva.fonttools.sstruct module again, which now lives in enable.kiva.fonttools.sstruct, there is only one item in the Git history. This is the same issue that we just saw - someone moved modules around in the Git repository and Git lost the history of this file. Let's go one level deeper and repeat what we just did - browse the history at the Git commit and try to find an older commit which we can explore further.

Inception - We need to go one level deeper

 

This time, we explore the GitHub repository at the commit a67d58bffd935aec385198f876645057d500d9e3. Here again, if we find the sstruct module and look at its history, we see the same problem - broken history. So, again, we go through the same process to find a commit where the git commit history for the module is intact.

Finally, we arrive at the following commit - c40a38cb216544a9da393503af47083b38f84b05. We can see that the sstruct module didn't exist in any previous commit so the module was introduced to git in this commit.

Now, if we explore the codebase to search for who uses the kiva.fonttools.sstruct module, we find that it is used by the vendorized fontTools module in kiva.

There we go. We now know when the sstruct Python module was added to the Git repository and who uses it.

Now, we need to understand why no one uses the sstruct module at the moment. This is simpler because we now just need to find out what happened to the vendorized fontTools code in kiva. If we look at the latest commit on the main branch, you will see that the vendorized fontTools code doesn't exist. So, at some point in the past, it must have been removed. We now need to find the PR where it was removed from the git repository. Searching through the merged Pull Requests on the enable GitHub repository leads me to the following PR - Remove vendored fontTools.

In that PR, the modules which use kiva.fonttools.sstruct are removed. Because no one else uses the sstruct module, it too could have been removed in the same PR but it looks like we didn't.

Finally, we have all the answers we need to resolve the original issue.

The sstruct Python module was added to the codebase to support the vendorized fontTools code. The vendorized fontTools has since been removed but we forgot to remove the sstruct module. So, we can now safely remove the module without worrying about any unexpecte repurcussions.