TOML and Working With Git Remotes
Tags: osd600
Published: 2023-10-08 03:09:57

### Links Mentioned
Project I worked on: [https://github.com/rabroldan/Waypoint](https://github.com/rabroldan/Waypoint)
Submitted issue: [https://github.com/rabroldan/Waypoint/issues/16](https://github.com/rabroldan/Waypoint/issues/16)
Submitted pull request: [https://github.com/rabroldan/Waypoint/pull/17](https://github.com/rabroldan/Waypoint/pull/17)

### TOML Configuration Files
For this week, my class was tasked with adding [TOML](https://toml.io/en/) 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](https://github.com/toml-lang/toml/wiki#implementations) 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](https://github.com/rabroldan/Waypoint), a text/markdown to HTML converter written in Python. I originally used `hukkin`'s [tomli](https://github.com/hukkin/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](https://peps.python.org/pep-0680/) 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](https://hacktoberfest.com/).
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](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) 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.