TOML and Working With Git Remotes

Links Mentioned

Project I worked on: https://github.com/rabroldan/Waypoint
Submitted issue: https://github.com/rabroldan/Waypoint/issues/16
Submitted pull request: https://github.com/rabroldan/Waypoint/pull/17

TOML Configuration Files

For this week, my class was tasked with adding TOML support to each other's Markdown-to-HTML converter projects. TOML, or Tom's Obvious Minimal Language is a format for configuration files. Adding TOML support allows users of our projects to pass optional arguments in a TOML document (config.toml for example). Our projects would have to first parse these TOML files before determining what optional arguments to use. Luckily, a list of TOML parser projects is available for developers to choose an implementation for their language. This saved us the hassle of implementing the parsers ourselves.

TOML support would be implemented by adding support for the following flag arguments: -c <file.toml> and --config <file.toml>. Passing these flags to the command line would override all other flags and apply optional arguments present in the TOML-file.

My Contribution

For this lab exercise, I contributed to rabroldan's Waypoint, a text/markdown to HTML converter written in Python. I originally used hukkin's tomli as the TOML parser, which would require future users to install tomli using pip:
pip install tomli. However, I later learned that a version of tomli, tomllib, was added to the Python standard library in Python 3.11 and later via PEP (Python Enhancement Proposal) 380 and used tomllib instead.

The Open Source Workflow

In this course, we've been learning and developing a feel the Open Source Workflow, a list of guidelines and rules of engagement for finding and contributing to open source projects. In the class, we've been practicing this workflow on our classmates, and recently on real-world projects for Hacktoberfest 2023.
From what I've done so far, the open source/contributing workflow I've learned looks like the following:

1. Find/make an issue (for a bug or new feature) and offer to work on it
2. Receive permission from maintainer(s) to work on the Issue (either on the Issue thread or on social media like Slack, Twitter, Discord)
3. Fork the project repo
4. Run git remote add <upstream-repo-name> <https://upstream-repo-git-url.git>
5. Run git checkout main/master and then git pull upstream main/master to ensure your fork is up to date
6. Run git checkout -b <topic-branch-name> to create a topic branch for the issue/feature you're working on.
7. Do your work and make commits to the topic branch until the issue/feature has been fixed/completed.
8. Run git push origin <topic-branch-name> to push your completed topic branch to your fork
9. Create a pull request to merge commits from your topic branch into the original project's main/master branch.
10. Repeat steps 4 to 9 if working an another bug/feature in the same project.

The Topic Branch Workflow

In this class we've also been developing what I call the topic branch workflow, which are guidelines to follow when working on a topic branch (step 7 of the Open Source Workflow). These are the general guidelines I've identified for the Topic Branch Workflow:

• Never work on or commit new code on the master/main branch
  • Features/bugfixes should be developed and committed in a topic branch instead
• Don't rewrite the maintainers' code your way
  • You should be adding new code in the maintainers' style
• Commits should tell a story
  • Make multiple small commits to show code maintainers how you arrived at a final implementation.
• Do not suffer in silence
  • If you need help, reach out to the maintainers for assistance

Since starting this class I think I'm starting to improve on these guidelines, especially making small commits and writing code in the maintainer's style. Although, this may be because I haven't tried making large contributions to large projects yet.

Git Remote

For this lab, we were advised to work with the git remote command. Git remote is a relatively new topic to me, although I've unknowingly been using git remotes ever since I cloned my first project (as Git automatically creates the origin remote). Based on what I've learned, it looks like git remotes can be used for three purposes:

1. Updating forked repositories
   • While in the local forked repository on a command-line:
   • Run git remote add upstream <original-repo-main-branch-git-url>
   • Run git checkout main
   • Run git fetch
   • Run git merge upstream/master
2. Testing Pull Requests
   • While in your local project repository on a command-line:
   • Run git remote add <contributor-name> <https://git-url-of-contributor-fork.git>
   • Run git fetch <contributor-name> to fetch commits and branches from the remote to your local repo
   • Run git checkout -b <tracking-branch-name> <contributor-name>/<branch-name> to create a tracking branch for tracking work on the branch
   • The tracking branch will be used to review and test a contributor's work
   • To update this local tracking branch, run the following:
   • git checkout <tracking-branch-name>
   • git pull <contributor-name> <tracking-branch-name>
3. Manually Merging Approved Pull Requests (After 2 - Tracking Pull Requests)
   • Run the following:
   • git fetch <contributor-name>
   • git checkout main
   • git merge <contributor-name>/<topic-branch>
   • git push origin main

So far, I've used it to update my own forks and to test and track a pull request, but I haven't yet used it to merge an approved pull request.

Conclusion

I need more experience working with git remotes. I'm still confused with what's happening when I work with a git remote, especially when working with branches of someone else's git remote. I hope to develop more experience with git remotes in the future.