Journaling Your Bugs For Fun And Profit

How documenting bugs can position yourself as a leader.

Content
1. How does a bug journal entry looks like?
2. Why documenting bugs?
3. Hugh Laurie :)
4. Samples from my stash: mainly docker and pandas issues.
5. Summary

Intro

Throughout my career as a software engineer and later as a data scientist, I have kept maintaining a journal of bugs and their corresponding fixes.

Hopefully at the end of this post, you’ll be convinced that writing down the mess you made is glorious!

The original bug log :) From

How Does An Entry Looks Like

Every single bug report is a reminder that encapsulates:
a. What led to borked system
b. What was the bug (including any stacktraces if exist)
c. What was the fix (including any links to external docs)

Why documenting?

Why am I documenting my bugs in a long-lived list?
I find it very valuable from several perspectives:

1. Same pros from any kind of journaling — a chance for retrospection, a sense of accomplishment. I have bugs from my first workplace, it’s kinda embarrassing looking at yourself with pimples at your teenage years but it has a potential for growth recognition at the same time.
2. Reproduction of the fix — you have fixed some configuration in a failed build. Optimally you should have .gitted that and in case this happens to a colleague, you can just send her the commit link. In case you forgot, or just didn’t feel the documentation belongs to version control, just send them your note.
3. Sharpen your writing skills — often we need to deliver various documentation. The process of distilling a bug into the components I’ve mentioned is a way to practice very important abilities. Bonus points for writing creatively while limiting yourself to only 1/2 curse words. +100 skills points for writing a Medium post about it 🙂
4. Position yourself as a leader — start documenting other processes. Be the one that others approach to when things go Ka-Boom. Warn your team ahead of possible future pitfalls.

A Side Anecdote

Here’s another point that other aspiring writers might resonate with.
Hugh Laurie, the actor that portrayed the wonderfully cynical doctor Dr. Gregory “House”, including many other roles (go watch Blackladder for some amazing British comedy (meme attached)!), have written a book called “The Gun Seller”.

Thanks MEMEBASE.com! This is Hugh Laurie, no joke

It’s one of my favorites books (amazon link), and I’ve enjoyed it immensely. In an interview, Hugh have mentioned a journal writing tendency. Due to his “boring” schedule at the time, he started to embellish some facts, until at some point his journal become to resemble the life of a James Bond with a slight Mr.Bean’ish attitude. That character became the protagonist of his book.

Who knows, maybe your bug journal will become a cyber-thriller some day!

Without further adieu,

My Own Stash of BUGS

3.3.22 — Can’t build a docker image

Debugging docker be like — from the awesome article

I was building a docker image, from the repository’s Dockerfile.
Building the docker image was stuck due to timeouts from tensorflow during:

pip install — no-cache-dir -r requirements.txt

I highly recommend no-cache-dir flag (why?) in Dockerfiles because it reduces the Docker’s image size.

Fixes:

1. Changed container base image to “slim-buster”
   Maybe the current base image has no prebuilt binaries for the “slim” version, which have caused compilation to native code. This might cause a big lag that could explain the timeout. THIS RESOLVED THE ISSUE
2. Update pip before advancing to “pip install”
   “RUN pip install — upgrade pip”
   Updating pip will update the different .wheels (.wheel file?) that pip can use for installation. One of the new found .wheel files probably had prebuilt binaries in the installation package that was qualified for my “slim” image. THIS RESOLVED THE ISSUE

3.2.22 — Broken DataFrame

Search debugging-pandas and that’s what you’ll get. From

Was doing different calculations on panda’s DataFrame, and assembling another data frame based on rows from the original.

The assembled data frame had weird behavior, counting a boolean column was returning the wrong results.

Basic logic:

1. Creating an empty dataframe()
2. Append rows from original data frame to the new daraframe

Fix:

Instead of creating an empty DataFrame

df = DataFrame()

Create a dataframe with identical column types as the original, like so:

df = DataFrame(columns=orig_df.columns)

Observation:

The column types of the new data frame were different than the original. That was the evidence that led me to the fix.

2.2.22 — Can’t transfer environment variables to a docker container through command line

This got me upset for couple of hours.

I’ve tried to pass AWS access and secret keys to a Docker container through following command:

docker run -e env tag

Fix:

Change the order of the parameters, env comes first!!!

docker run tag -e env

Summary

There are many ways to grow as an engineer, and I think that documenting for your own purpose and for others is one of them. It might be even fun, functioning as an outlet to your amassed frustration.

Quoting a dear friend of mine:

a bug is an opportunity to improve your understanding of the system.

If you liked this post and want to tap on my shoulder in a friendly matter, you can “clap” and “follow”. Thanks!