lab 4 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Lab 4
Due Date
Friday Oct 7th 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 continue to add a new feature to our SSG 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
- 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 SSG Feature: Support --config with Config File
Description
Users want to be able to specify all of their SSG options in a JSON formatted configuration file instead of having to pass them all as command line arguments every time. For example, consider the following config file, ./ssg-config.json:
{
"input": "./site",
"output": "./build",
"stylesheet": "https://cdn.jsdelivr.net/npm/water.css@2/out/water.css",
"lang": "fr"
}
A user could run the SSG by doing either of the following:
# Option 1: use command line arguments:
ssg --input ./site --output ./build --stylesheet https://cdn.jsdelivr.net/npm/water.css@2/out/water.css --lang fr
# Option 2: use a config file
ssg --config ./ssg-config.json
The config file option means we can have a much shorter command, and instead store our options in a file.
Requirements
- The
-cor--configflags accept a file path to a JSON config file. - If the file is missing, or can't be parsed as JSON, exit with an appropriate error message.
- If the
-cor--configoption is provided, ignore all other options (i.e., a config file overrides other options on the command line). - The program should ignore any options in the config file it doesn't recognize. For example, if the SSG doesn't support stylesheets, ignore a
stylesheetproperty. - If the config file is missing any options, assume the usual defaults. For example, use
dist/as theoutputdirectory if it isn't specified.
Here are some valid config files to try:
{}
{
"input": "./docs"
}
{
"input": "./docs",
"output": "./web"
}
{
"input": "./docs",
"output": "./web",
"future-feature": "should be ignored for now"
}
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 SSG repo. Pick a new repo from the 0.1 Submissions list, ideally one that you haven't worked on before. You may NOT add it to your own repo. Only one student can add the feature per repo.
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
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.
To do so, you are encouraged to create a Draft Pull Request at the start of the week and continually add more commits to it as you do your work. 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".
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. 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>
This 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>
# substitute master for main if that is your default branch
$ 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.