lab 3 - humphd/topics-in-open-source-2024 GitHub Wiki
Lab 3
Due Date
Friday Sept 27 by Midnight.
Overview
This week we are going to practice using git to manage multiple simultaneous changes in a single project, and use git merges. To do this we'll continue to add some features to our 0.1 repos. This lab will help you practice the following:
- creating multiple branches to work on new features and fix bugs
- working on multiple code changes in parallel on separate topic branches
- adding features to existing code
- using
git mergeto dofast-forwardandthree-way-recursivemerges - fixing merge conflicts
- how to find and identify commits on GitHub
Step 1. Pick your Features
You are going to make changes to your own 0.1 repo (i.e., you can work on your own code this week). Pick 2 of the following features to add to your project:
- Support multiple files and/or folder arguments. It should be possible to pass your tool multiple files and/or folder paths, and the files within should get processed.
- Make sure that the program exits with appropriate error codes and helpful error messages (stderr) in all cases. If there are no errors, exit with
0. Otherwise, exit with a non-zero exit code (e.g.,1). - Add support for another provider other than the one(s) you currently use. For example, add support for Cohere, Gemini, Grok, OpenAI, OpenRouter, etc. Talk to your classmates who already use these providers to get tips on how to do the integration.
- Allow using multiple models at once. The user should be able to specify multiple models, and output files should get generated for each model, allowing for comparisons.
- Add support for streaming responses with
--stream/-s. When writing tostdoutyou will stream the response live as it updates vs. all at once at the end. - Add support for using a
.gitignorefile to exclude files/folders when processing a directory. If the user has a.gitignore, parse it and use that to build filesystem glob patterns to ignore - Pick another feature to implement of your own choosing. Confirm that it's OK with your professor (it probably is).
In your project's GitHub repo, file Issues for each of the two features you want to add, and discuss the changes you will make in the Issue's descriptions. Make sure the Issues are complete and detailed.
Step 2. Create Topic Branches
For each of your chosen features, create a new, separate topic branch. For example, if you filed Issue #10 and Issue #11 you need to create 2 new topic branches off of main:
$ git checkout main
$ git checkout -b issue-10
$ git checkout -b issue-11
All work for Issue #10 should happen on the issue-10 branch. All work for Issue #11 should happen on the issue-11 branch. None of your work should happen on main (we'll only merge there). All work should be done on one of the topic branches you just made.
NOTE: you switch between your branches using git checkout issue-10 or git checkout issue-11 (use your branch names). You can only switch branches if your working directory is clean (i.e., you committed any changes).
Step 3. Implement Your Features
Throughout the week work on your two features. You are free to discuss strategies and ideas with your classmates, but you must do your own work in the respective branches you created above (no pull requests this time, sorry!).
Your two features will likely involve modifying the same files and/or functions. This is fine and to be expected. Resist the desire to share any code between branches! Keep all work for each feature in its own topic branch, and touch as little code as possible in each branch. The less code you change, the easier it will be to merge everything later.
You can work on the features one after the other, or in parallel, but you may not merge until both are done! With software, it's common and often helpful to do more than one thing at a time: if you get stuck on one, you can switch to the other.
One of git's powers is to allow you to have many different versions of the same code all in existence at the same time. This lets you quickly move back and forth between different projects on the same repository, without having to worry about losing your work.
Remember to git add and git commit as you go, and put all your commits on the correct branch. Every change for Issue #10 goes on the issue-10 branch, etc.
Step 4. Merge Your First Feature Branch
When you have completed both features, and each branch contains the necessary code, it's time to merge.
We merge into a branch, so start by switching to your default branch (i.e., main) and merge the first feature branch (e.g., issue-10):
$ git checkout main
$ git merge issue-10
This merge should go smoothly, and assuming you haven't changed anything on main since you created your topic branches, git will do a fast-forward merge. Confirm that it did, using git log. If it didn't, determine why not.
Step 5. Merge You Second Feature Branch
After you've merged your first branch, it's time to merge the second (e.g., issue-11):
$ git checkout main
$ git merge issue-11
This merge will likely require a three-way recursive merge, since git can't fast-forward your main branch. You may also need to deal with merge conflicts.
Make sure you fix any/all merge conflicts before you complete the merge. If you need help, ask on Slack.
When you're done, the main branch should contain the code for both feature branches, and both features should be working. Make sure your merges didn't break anything!
Test, test, test, and test again. Is the main branch still working? Do you need to fix anything before going to the next step? If so, commit to main to correct the problem(s). Keep track of this, and discuss in your blog below.
Step 6. Push your Main Branch to GitHub
Push your fully merged and tested main branch to GitHub:
$ git push origin main
Step 7. Close your Issues
Close your original issues, and provide a link in the comments to the merge commit on GitHub that closes the feature. On GitHub the URL for a commit follows this format:
https://github.com/username/project-name/commit/commit-sha
For example, the 11a9e21d73df8cbd67db7163b42b30e052fbcca0 commit (which we can shorten to 11a9e21) for this repo is at:
When you close your issue, add a comment like this:
Step 8. Write a Blog Post
Write a blog post about the process of working in parallel branches in your project. In your post, include links to everything you discuss (e.g., the project repo, your issues, your merge commits).
Discuss what you did, the changes you made for your features, and the process of doing your merges. What problems did you have? What did you learn? What would you do differently next time?
Submission
When you have completed all the requirements above, please add your details to the table below.