A Jump Into the Deep End: A First Attempt at Open Source Code.

I have been coding for roughly six and a half months, and I am by no means an expert; however, at this point in my life pivot towards software development I am certainly feeling a little confident in my abilities. The Turing School of Software and Design will do that for you. In the past months I have been tasked with learning a lot, very quickly, understanding it and building out well working (sometimes) applications, and, after all the hours, the new technologies, the code tears, etc, etc. I must say that being asked to dive into an existing open source code base, find an issue, solve it, and open a PR on it, may be the most intimidating thing I have been asked to attempt to date at Turing.
Myself and three other brave souls were given the vets.gov site to work with. This site is designed to be used by veterans of the US armed services in order to research and apply for the different types of benefits they are eligible for through the Department of Veterans Affairs. The site is being developed as a new portal for researching and applying for VA benefits. The current VA site is without a doubt in need of an update, and finding the information presented at vets.gov is much harder to locate at va.gov.
Diving into the codebase:
The repo for vets.gov was well documented. The readme presented all the necessary info we needed in order to clone down the repository, set up our dependencies and run the app locally on our machines. There was additionally a section discussing file structure and different libraries being used to help compile and run the app. While the documentation was thorough albeit slightly outdated, we still spent the better part of a day and a half attempting to parse through the code base and understand how all the components were speaking to each other. Now, at this point in my career in software development, I thought I felt comfortable working in React/Redux. I have made several applications and feel confident in my understanding of the lifecycles and how state is handled and passed between components. What we found within this codebase however was certainly humbling. The shear quantity of components, most of which are reusable gave me a renewed appreciation for the power and efficienty of React. After the initial sticker shock so to speak of the size and complexity of the repo, we began to identify the features, libraries, and technologies we were unfamiliar with. It felt prudent to continue to understand how all the files were speaking to each other before making an attempt to alter the codebase.
What was new and interesting?
While there there were a few libraries and technologies that I was unfamiliar with being used within the codebase, due the overall complexity of the file structure I found myself particularly interested in determining how all of the files were being compiled together and into a functioning site. In the case of vets.gov, the codebase was utilizing a JavaScript library called Metalsmith. The Metalsmith site describes it as “an extremely simple, pluggable static site builder.” What this does is read a source file or any number of source files, extract their information, manipulate it in some way, the rewrite the information into new files into a destination directory.
Metalsmith(__dirname) // instantiate Metalsmith in the cwd
.source('sourcepath') // specify source directory
.destination('destpath') // specify destination directory
.use(markdown()) // transpile markdown into html
.use(layouts({ // wrap a handlebars-layout
engine: 'handlebars' // around transpiled html-files
}))
.build(function(err) { // this is the actual build process
if (err) throw err; // throwing errors is required
});The above example from the Metalsmith docs was very relevant to the vets.gov repo. They used markdown files to create and write many of the html structure of the site. As we had not seen this before, were very confused to see such a large number of markdown files in the codebase, especially as we were searching for html tags to identify. As the above snippet shows, vets.gov was using Metalsmith to transpile markdown files straight into html for the site build. With this being the first time we encountered Metalsmith it was very enlightening to dive into the documentation to see how it can be used to leverage a large file directory into a single deployable build.
What did we do?
Now, with some background on what we had gotten ourselves into, it would only be appropriate to discuss the issue we as a group of very green developers attempted to accomplish. There were several unclaimed issues in the repo that we gauged as reasonably doable. One particular issue that dealt with some styling and CSS on mobile view was slightly unclear to us, so one of our group members reached out for clarification on the issue. Unfortunately we did not receive a response soon enough, so we decided to collectively address one of the issues. The issue we addressed requested a check to prevent users applying for education benefits to not be able to add secondary information cards to their form without providing at least some information. In its current condition, the form will create a data card with a somewhat hacky note of “This card may be missing information”. Without getting to entrenched in the complexities of the code, in order to resolve this issue, we added a check on whether or not any one of the input fields had a value. If all were empty, then a function would be called to scroll the screen back up to the top of the form. This was per a suggestion from maintainers who opened the issue. If any field had a value it would add a card to the form. The pull request detailing our changes can be viewed here.
In the process of working on our issue we did come across another issue within the same area of the codebase. Prior to the fix we implemented we realized that upon submitting any card with secondary education information, on click of the ‘add another’ button, the card would be created, but the original input fields would be replaced by the edit card component, thus rendering two cards for every click. As this was not part of the original issue, we submitted our PR addressing the empty card issue but also recommended that maintainers open a seperate issues addressing the duplicate card creation.
Takeaways
For a first attempt at contributing to an open source project, I would say this was a humbling and incredibly valuable experience. I was good to get outside of my comfort zone and see how large codebases responsible for building entire sites are organized. I will say that while we had a set timeline for submitting our PR, I still do not have a full grasp of the how the site is working as a whole. Even if I had spent all four days just trying to parse through the file structure, I think my understanding would still be foggy. This can be expected though with such a large codebase. It was challenging to take on issues as well give the relative unresponsiveness from maintainers. As I mentioned before, on one where we asked for clarification, we received no response. Additionally some PRs were opened years ago and had not be touched since.
My advice to anyone else waffling on whether or not to dive into an open source code base would be…do it. Regardless of outcome, or a merged PR, gaining the exposure to unfamiliar codebases can only benefit you as a developer. I know I’ve gained a lot from the experience despite the pending PR, which if I’m being honest, will probably sit in limbo for a while. Take some time to find a project that sounds interesting, and check to see that there is frequent and recent activity in the repo. If anything you will get to connect with developers and most likely gain exposure to new technologies in the process.
