Using Git Remote To Collaborate With Peers

This week has been exceptionally busy for me, as it marks the first week of Hacktoberfest. I've been documenting my journey so far in a detailed post, which you can check out here.

TILvert

In addition to Hacktoberfest, I've been working on adding a new feature to one of my peer's projects called TILvert. TILvert is a command-line tool designed to process .txt and .md files, generating a valid HTML file based on their content. It offers various options for customization, with -v and -h being the most basic. Other options include --stylesheet, --language, --title, and more. To contribute, I created an issue on the project repository outlining the changes I planned to make.

The Process

Once the author approved my proposed changes, I followed these steps:

1. I forked the repository and cloned the forked copy onto my local system. It's important to note that a forked repository doesn't automatically update when the original one receives new updates. To link my local repository to the original, I added a remote called upstream using the following command:

git remote add [remote-name] [git-url]

1. After confirming the addition of the upstream remote by running the git remote -v command, I created a new branch with a name corresponding to the issue number I had created earlier using:

git checkout -b [branch-name]

1. I then opened the README file and followed the instructions to build the application. While the build was successful, running the application resulted in an unhandled exception. I investigated the issue and discussed potential solutions with the owner of the repository. They promptly fixed the issue on their end and merged the changes into their main branch.

2. To incorporate these changes into my local repository, I switched to my main branch and used the git pull upstream/main command, which combines the git fetch upstream and git merge upstream/main steps. This was possible because the upstream/main branch was only one commit ahead of origin/main. After this merge, my issue-11 branch lagged by one commit. To resolve this, I executed the following command:
   

git checkout -B issue-11 main

Using the checkout command with the -B flag updated the issue-11 branch to point to the same commit as the main branch.

Throughout the development of this new feature, there were a couple of instances where the author pushed new changes to their repository, but the process to retrieve them remained the same.

Code Contribution

Adding the required code to the project was relatively straightforward. The application was already set up to accept and process command-line arguments efficiently. I only needed to introduce a new argument with the required details and implement a simple check at the beginning of the main function to detect if a config flag was used. If a valid TOML file was found at the specified path, I parsed it using the toml package and used it to override the values provided through the command line. In cases of errors or missing config files, the application displayed appropriate error messages. Additionally, I noticed an issue with the language attribute not being set correctly, whether from the command line or the config file. Although this issue was unrelated to my contributions, I addressed it with a separate commit. Finally, with the code ready, I created a PR for the author's review.

Learning Experience

This week has been a tremendous learning experience. I acquired new knowledge about Git, such as how to navigate different PRs and commits, and how to revert changes and return to specific commits within a branch. Beyond Git, I also gained a valuable lesson in project contribution. It's crucial to clone and run an open-source project to ensure it functions correctly before committing to any contributions. During this project, I encountered a few bugs specific to the Windows OS, which the author had not anticipated since they developed the code on Linux. These bugs surfaced one after another, and resolving them to get the application working took several days. While I could have reported these issues to the author and moved on to another project, I don't regret the experience, as it provided an excellent opportunity for learning and skill development.