TOML for lazy developers

Hello all! My name is Peter Wan, and I'm a student at Seneca Polytechnic, studying Computer Science.

This week in my Open Source Class, my classmates and I were tasked with adding a new feature to another classmate's command-line (CLI) tool. Before getting into what this feature was, I'd like to give you some context on the CLI tool I worked on.

The CLI tool I worked on is called, barrierless and was made by my friend, Vinh Nhan.

The barrierless CLI tool uses different large language models (LLMS), such as Groq's llama3-8b-8192 or Gemini's gemini-1.5-flash model to take one or more files and convert them into another language.

Let me show you barrierless' basic syntax:

bl-bot [files...] -l <language> -o [output files...]

Now, let me show you an example of me using barrierless to convert an English file and a Chinese file into two separate files in French:

bl-bot examples/en-file.txt examples/cn-file.txt -l french -o french-file-1.txt french-file-2.txt

If possible, I wanted to be able to assist Vinh with adding a feature that lets the user specify some defaults so as to save his users from typing a lot.

To that end, I made sure that Vinh's users could now specify some of their defaults in a custom TOML file, called .barrierless.toml. Each user that installs barrierless can choose to create this file in their home directory, if they wish to establish some defaults for the barrierless CLI tool. Let me show you mine:

You'll notice that I've specified the default language, that is, the language the files will be converted into as french.

Now, users that are savvy enough with configuration can simply write:

bl-bot [files...] -o [output files...]

instead of:

bl-bot [files...] -l french [output files..]

Thankfully, implementing this feature wasn't too difficult. It was just a matter of using this TOML parser called 'toml' to read the .barrierless.toml file in a user's home directory.

There were some checks that I added to ensure that Vinh's program could run smoothly with or without a .barrierless.toml file, I've highlighted the code that I added:

https://github.com/vinhyan/barrierless/blob/764bf99c18c1507604baa130dd6a080f2ef2f5c8/src/util.js#L6-L33

This function's logic ensures that if there's no .barrierless.toml file, then the program doesn't have to worry about it. If the .barrierless.toml file does exist, attempt to extract the data from it (assuming it's a valid TOML file), if the file exist and it is not a valid TOML file, throw an error.

This way, pre-existing users of Vinh's program that don't have a config file can use it like before, and other users that wish to add a config file can get feedback if their file isn't configured properly.

That's about all I'd like to talk about with regards to the features I added, but I also want to discuss my development process for those that are beginning to use git and GitHub to contribute to another person's repository.

My process involved doing the following:

1. Visiting Vinh's barrierless repository, and making my own fork of his repository.
2. Copying the ssh link needed to clone my fork onto my local machine:

1. Running the following command to clone my fork onto my local machine:

git clone git@github.com:peterdanwan/barrierless.git

1. Adding Vinh's upstream repository as a remote link to my local repository, so I can keep track of any updates Vinh makes to his copy of barrierless:

git remote add upstream https://github.com/vinhyan/barrierless.git

1. Fetching all recent updates made to Vinh's repository such that my local git repository is aware of those changes (this can be run on any branch and should be run often):

git fetch upstream

1. Merging Vinh's upstream main branch into my local main branch (NOTE: I am on my main branch when I run the command below):

# Merge the changes from upstream/main into my local main branch
git merge upstream/main

1. Make a topic branch called issue-19 based on the issue number I'd be working on.

git checkout -b issue-19

1. Add files to the staging area and commit my changes (I repeated this step quite a bit)!

git add [files...]

git commit -m "my commit message"

1. Pushing my changes to my forked copy on GitHub (this is run whenever I have a local change that isn't up on my forked repository's issue-19 branch):

git push origin issue-19

1. Make a pull request on GitHub asking asking to merge my issue-19 branch into Vinh's main branch.

This Git and GitHub process as you can see, was quite involved, but not so bad once you're used to the workflow.

Somethings to keep in mind are that I have 2 remote repositories that my local git repository is aware of:

1. upstream: representing Vinh's repository
2. origin: representing my forked copy of Vinh's repository

In order to make sure my pull request is as smooth as can be, I constantly run the following commands to ensure that my commits can sit on top of any recent changes to Vinh's main branch:

# Download the changes from Vinh's GitHub repository into my `upstream` remote
git fetch origin

# Ensure I'm on my local main branch
git checkout main

# Merge Vinh's up-to-date changes from his GitHub's main branch into my local main branch (I am on the main branch when I run the command below):
git merge origin/main

# Ensure I'm back on my feature branch I made earlier
git checkout issue-19

# Have my commits sit on TOP of any recent commits made to my local main branch (which is currently in sync with origin/main):
git rebase main

# ... add files, commit, and push my changes like usual

If you made it this far, let me just say - thank you! I hope that both the background of Vinh's repository and the git commands I used serve some purpose in your development journey as well.