Sometimes The Setup is Harder Than The Change

I found myself trying to look for a relatively simple pull request to get warmed up to Hacktoberfest. After a fair bit of poking around, and prodding at an issue in another repo for a library that I had actually used as an end user over the summer, I found an issue that looked relatively straightforward to help me get my foot in the door in a new and unfamiliar repo.

The issue was to change some styling on a search page to help differentiate clickable menu items from non-interactive headings. The creators of the repo did a good job in providing a screenshot, and working link to running code that illustrated the issue here. They also provided a quick start guide for setting up the coding environment, and some additional tips on working with the virtual machine that comes with the repo.

The project I aimed to contribute to is LibreCores, a website that hosts open source electronic hardware designs. The project is written in PHP using the Symfony framework. For its development environment, it uses Ansible and Vagrant to launch an Ubuntu virtual machine that runs an NGINX server that updates much of its content live as you make changes to the code.

In other words, the project has a fairly impressive setup to allow developers to reliably test their code in a highly portable development environment. Portable--that is--if you either have a hardware machine running Ubuntu, or a similar Linux distro, or if you have a hypervisor software that can run a 64 bit virtual machine inside another 64 bit virtual machine. While some offerings from VMWare can allegedly do nested 64 bit VMs, being a VirtualBox user, I seemed to be out of luck. It had dawned on me that my current laptop was a bit short on space to install yet another virtual machine, so out came an old laptop mostly constructed of superglue and the blind optimism of a student too cheap to buy a bigger hard drive.

After reformatting the hard drive on my plastic lump of thriftiness, and installing a new copy of Ubuntu 18.04, I set out to get the development environment running on my machine. This both was, and was not, straightforward. As mentioned, the main contributors to the LibreCores repo had take the time to set up a decent set of instructions, and they had even taken the care to create a nice bash shell script in the repo to install the bulk of the dependencies (Vagrant, Ansible, VirtualBox and an accompanying Ubuntu image, etc). What was not immediately clear from their instructions, however, was that the LibreCores site uses an API called Algolia to provide search functionality for LibreCores' database of hardware. Algolia allows you to create related schema of objects, and to define how the priority with which they are retrieved in response to certain search keywords. Access to the Algolia API was not provided directly with the repo, and this was what populated the one part of the page that I wanted to change for the issue I was working on.

The idea was that devs were either supposed to provide their own API secrets and app IDs to allow the app to interface with Algolia (however only user authentication was mentioned in the Quick Start guide). This was easy enough to do so I created a trial Algolia account, copied over the necessary secrets, to the code I was working on, and realized that I had no idea how to get data from the LibreCores code repository over to Algolia. There was documentation that allowed you to run some commands that copied the schema ("Indices") over to Algolia so that data was defined, but if starter data was provided, I had no idea how to get to it, as all the MySQL database the project came with was also empty aside from the table layouts.

In the end, I remembered that the nice fellow who wrote the original issue had provided a link to a live version of the part of the app I was supposed to look at. While I certainly couldn't make changes to this without far more knowledge in subverting computer security than I'm currently blessed with, I chose to open the developer console in my browser, and steal all that precious JSON that came back as a response from the example search query that example server was running. It was then a (fairly) simple manner of going into Visual Studio code, and taking advantage of their "jump to bracket" hotkey (Ctrl + Shift + \ ) to cut off some of the wrapping JSON and get at the pre-packaged JSON objects I was looking for. These were then loaded into Algolia via my account dashboard through my web browser.

...Oh, right... And then I changed about 18 lines of code in 2 files and submitted a pull request.