lab 4 - humphd/topics-in-open-source-2024 GitHub Wiki
Lab 4
Due Date
Friday Oct 4th by Midnight.
Overview
This week we are going to practice using git remotes and merges to collaborate with our peers on some code changes.
To accomplish this we'll once again add a new feature to our 0.1 Release app repos. This lab will help you practice the following:
- creating branches to work on new features and fix bugs
- working on a more complex code change in another project you didn't write
- working with and parsing TOML files
- using
git remoteand sharing commits, branches - using tracking branches
- understanding the difference between
git push,git pull, andgit fetch - working with Draft Pull Requests on GitHub
- reviewing and testing a branch from another repo locally
- using
git merge - using
git pushto update a remote repo - manually closing pull requests by merging/pushing
NOTE: it is highly recommended that you watch this week's video on git remotes before you start this lab. We're going to use a number of features of git that are important to understand going forward, so please ask questions if you get stuck.
New Feature: Support using a TOML "dotfile" config file in the user's homedir
Description
Users want to be able to specify all of their options to your tool in a TOML formatted configuration file that they store in their home directory, instead of having to pass them all as command line arguments every time. For example, consider the following config file, ~/.your-toolname-config.toml:
model = "gpt-4o"
api_key = "sk-...."
# etc...
Then, when the user runs your tool, it will search for a config file in the home dir and use those values. Or, if the user specifies values via args, those will override the default ones in the config.
NOTE: there are many open source TOML implementations you can use to parse the config file. Don't write the parser yourself, pick a well maintained library instead.
Requirements
- The tool should look in the home dir for a "dotfile" TOML config (i.e., a file that starts with
.and contains default options in TOML format) - If the file is missing, ignore this
- If the file is present but can't be parsed as TOML, exit with an appropriate error message.
- If the file exists and no command line args override any values, the values in the config file should be used (e.g., use the model in the config)
- The program should ignore any options in the config file it doesn't recognize.
Step 1. Pick a Repo to Work in and File an Issue
You are asked to add this new config file feature to another student's repo. Pick a new repo from the 0.1 Submissions list, ideally one that you have NOT worked on before. You may NOT add it to your own repo. Only one student can add the feature per repo. You don't need to work as partners on each other's repos, but you can if you like.
Before you begin, check to see if an Issue is already filed for this feature. If it is, move on to another repo. If not, file a new Issue, letting the owner know what you intend to do, and start talking to them about how you should do it via Slack or in comments in the Issue on GitHub.
NOTE: if you notice two people filing the same issue in your repo, make sure you close the second one as a duplicate of the first.
Step 2. Create and Work on a Topic Branch
Fork and clone your partner's repo to begin your work.
Create a new topic branch for this work. If you filed Issue 6, consider naming your branch issue-6. You could also name it config-file, the naming is up to you.
Do all of your work on this branch, committing every significant change as you go.
You should also git push your branch to your fork on a regular basis. To do so (substitute your branch name for issue-6):
$ git push origin issue-6
The origin remote is the repo from which you cloned, and is automatically created when you clone a repo.
You can find your work on GitHub using the appropriate URL for your branch, for example:
https://github.com/{your-username}/{your-fork-repo-name}/tree/{your-branch-name}
Step 3. Collaborate with the Repo Owner
Create a Draft Pull Request at the start of the week and continually add more commits to it as you do your work over the week. A Draft PR is a work-in-progress, and you can keep updating it until it's ready for review, at which point you can change its status to "Ready for review".
Throughout the week, as you work on the config file feature, keep in regular contact with the owner of the repo. Don't wait until things are finished to get in touch. You are likely going to run into problems, have questions, or need advice on how they want something handled. Work in the open and force yourself to communicate and help one another.
Step 4. Complete the Feature
When you have completed the feature, commit and push all the changes on your branch to your fork:
$ git checkout issue-6
$ git push origin issue-6
Let the other student know that you're done in the GitHub Issue. Mark your Draft PR to "Ready for review", and ask the owner of the repo to review and test your code.
Step 5. Reviewing and Testing via Remotes
When you are reviewing and testing a PR, you often need to both read the code and also test the functionality locally. We know how to clone a repo, but how do we work with a different repo that we didn't clone? The answer is to add a git remote.
If your repo is being worked on by another student, get the name of their fork and the name of the branch they are working on. Next, add them as a remote to your local repo:
$ git remote add <name-of-student> <https://git-url-of-other-studnet-fork.git>
The https://...git URL is the same one you'd use to clone this repo (i.e., it is NOT the web URL you use in a browser, notice the .git extension). You can name the remote anything you like. Just remember what you called it. You can use git remote to list your remotes later, if you forget.
Next, git fetch their work into your local repo:
$ git fetch <name-of-student>
Using git fetch will download all the commits and branches in the remote repo to your local repo, but NOT merge anything (i.e., it's safe to do on any current branch). Everything they have in their repo is now copied to your git repo.
Next set up a tracking branch in your local repo, so you can track the work on their branch (substitute the name of the student and branch):
$ git checkout -b <branch-name> <name-of-student>/<branch-name>
This will create a branch in your repo that points to the same commit as the other student's repo and branch.
Use this branch to review and test their work. If you notice any issues, or something doesn't work, make comments in the pull request. Ask the author to fix their work.
NOTE: if you ever need to update your local tracking branch to see new changes that the other student has pushed to their fork, you can do that with git pull (assuming tracking branch is called issue-6):
$ git checkout issue-6
$ git pull <name-of-student> issue-6
If you have any trouble working with git during this process, make sure you ask for help in Slack. It is important that you understand how these commands work, so don't skip anything, and don't give up if you're confused!
Step 6. Merge the Feature When Ready
For the owner of the original repo: once you are satisfied that the feature is complete, and the pull request is done, try merging it manually and pushing to your repo:
$ git fetch <name-of-student>
$ git checkout main
$ git merge <student-name>/issue-6
$ git push origin main
Merging the work and pushing to the main branch should automatically close the pull request.
Step 7. Write a Blog Post
Write a blog post about the process of working on this new feature using remotes. First, how did the code itself go? Did you run into any problems? How did you tackle the work? Second, how did it go using git? Did you find any of it difficult? How did you get around this? What would you do differently next time? What did you learn from the experience?
Submission
When you have completed all the requirements above, please add your details to the table below.