lab 3 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Friday Sept 30 by Midnight.
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 SSG 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
You are going to make changes to your repo (i.e., you can work on your own code this week). Pick 2 of the following features to add to your project:
- Add an optional
-l,--lang, and/or\lflag, which indicates the language to use when generating the lang attribute on the root<html>element. For example,--lang frwould mean that the HTML documents are in French, and would include<html lang="fr">, while-l pt-BRwould mean the text is using Brazilian Portuguese:<html lang="pt-BR">. By default, useen-CAfor Canadian English. - Make sure that the program exits with appropriate error codes 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 inline
<code>blocks. In Markdown, enclosing text in a single backtick causes the text to HTML to get rendered as<code>...text...</code>. - Add support for a horizontal rule in Markdown. The Markdown
---should get converted to an<hr>tag. - 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.
For each of your chosen features, create a new topic branch. For example, if you filed Issue #10 and Issue #11 you need to create 2 new topic branches off of master (or main, depending on what your default branch is):
# change master to main if that's your default branch
$ git checkout master
$ git checkout -b issue-10
$ git checkout -b issue-11All 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 master! 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).
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. 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.
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., master or main) and merge the first feature branch (e.g., issue-10):
# change master to main if that's your default branch
$ git checkout master
$ git merge issue-10This merge should go smoothly, and assuming you haven't changed anything on master 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.
After you've merged your first branch, it's time to merge the second (e.g., issue-11):
# change master to main if that's your default branch
$ git checkout master
$ git merge issue-11This merge will likely require a three-way recursive merge, since git can't fast-forward your master 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 master 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 master branch still working? Do you need to fix anything before going to the next step? If so, commit to master to correct the problem(s). Keep track of this, and discuss in your blog below.
Push your fully merged and tested master branch to GitHub:
# change master to main if that's your default branch
$ git push origin masterClose 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:
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?
When you have completed all the requirements above, please add your details to the table below.