lab 2 - Seneca-CDOT/topics-in-open-source-2022 GitHub Wiki
Lab 2
Due Date
Friday Sept 23 by Midnight.
Overview
This week we are going to practice contributing and submitting Pull Requests to other repos we don't own. This lab will help you gain experience doing the following:
- forking and cloning other projects
- creating branches to work on new features and fix bugs
- working on code you didn't write, trying to maintain the original style and not break things
- working with Markdown
- creating pull requests
- collaborating with other developers on GitHub
- reviewing code changes
- updating your pull requests to include fixes for review comments
Step 1. Pick a Project
Pick another student's SSG project from the Release 0.1 Submissions list. You can work on any project other than your own, and you do not need to work with the same partner each week. Ideally, make sure no one else is working on this repo (one student per repo for this lab, please).
Step 2. Pick a Markdown Feature to Add
You are asked to add initial support for Markdown in your partner's static site generator. Markdown is a simple addition to plain text files that allows for document formatting and structure to be applied easily. It is much simpler than HTML, but supports many of the same features. This document was written in Markdown, which GitHub used to create the HTML you see in your browser.
You will make two changes to your partner's repo:
- Modify the file handling so that it supports both
.txtfiles as well as.md(i.e., Markdown files). If the file extension is.txt, process the file exactly the same way it is done now (i.e., no changes). However, if the file extension is.md, add some extra processing (a new function, another class, a new module, etc. as makes sense) to parse one aspect of Markdown into HTML. - Choose at least one of the Markdown syntax features for Italics, Bold, Heading 1, Heading 2, or a Link and implement it.
NOTE: please hand-code your Markdown support vs. adding an existing open source Markdown parser, library, or framework. You can switch to a full markdown-parser in later weeks. Initially, I want you to try implementing this manually.
Step 3. File an Issue
Search through the existing Issues to make sure no one has filed an Issue for Markdown support yet. If there is one already, move on to another project repo.
If there isn't, file an Issue to add Markdown support. Describe what you want to do, and mention that you'd like to work on this. Give enough information for the project owner to understand what you plan on doing, and give feedback about how they want it done.
Step 4. Fork, Clone, Branch
Fork the other student's project on GitHub, then clone your fork. Next, create a branch for your work. If you filed Issue #5, name your new branch issue-5:
git checkout -b issue-5
Do all of your changes (i.e., all of your commits) on this branch, not the main branch.
Step 5. Write the Code
First, read the existing code. Get a sense of how it's organized (files, classes, functions), and make sure you can run it. If the code is broken before you begin making changes, it will be hard to test your work. If you're unclear about how something is written, ask the owner for tips. Remember, open source is a team sport. You don't need to struggle on your own in silence. Use the community to discuss your work and get help.
Once you understand the existing code, start making changes to the existing code in order to implement your Markdown support. Make sure you write your code as closely to the style of the original author as possible. Make it look like the same person wrote all the code. Pay attention to how they name things, how they do formatting, where they put things, etc.
Try to change as little as possible in the existing code. Don't start rewriting everything because you like a different style. Don't touch code that is unrelated to your changes. Don't fix bugs unrelated to your current work (that should be done in another issue, pull request, branch). Be focused! Touch only the code you need to in order to make your changes work. Write as little code as possible, while still making sure the feature works. NOTE: if you do find other bugs while you are working, feel free to file additional issues in the other student's repo.
As you work, commit changes to your branch. For example, you might start by adding support for .md files along with .txt. Once that's written, you should commit your code before proceeding further. Your commits should be small, and tell a story: "Get the first part working", "Get the second part working", etc.
Make sure your changes don't break the original code. Test, test, test, and test again. When you are satisfied that things are working, proceed to step 6.
Step 6. Update the Docs or Other files
Because your code is adding a feature, it's likely that you need to update other non-code files as well. For example, the docs (README) will need to be updated with info about Markdown, as well as discussing how to use the particular bits of Markdown you added. There could be other files that need to be updated as well.
Making changes to a project often involves updating code, tests, dependencies, etc. Make sure you look for all the places you need to update things. Include all of these related changes in your branch.
Step 7. Create a Pull Request
When you're finished Steps 1-6, create a Pull Request. Start by pushing your branch to your fork on GitHub (i.e. your origin). Assuming you were working on a branch called issue-5:
git push origin issue-5
Obviously you should rename issue-5 to the actual branch name you are using.
Follow these steps to create a Pull Request from your branch. Pay attention to the following:
- Pick the correct branch in your repo (e.g.,
issue-5for you andmasterormainfor the original repo). You want your work to get merged into the original project'smasterormainbranch eventually - Write a complete title for your pull request. For example, "Add initial support for Markdown"
- Write a complete description of what you did, including info that this
Fixes #5(or whatever Issue number you are fixing). GitHub will automatically link an Issue and Pull Request for you if you use the correct syntax. In your description, talk about what you changed in the code, how you did it, explain why you made certain choices, and discuss any problems you encountered or bugs you know about. Make sure the project owner can understand why and what you want to change with your pull request. Be detailed!
Step 8. Get Feedback and Update your Pull Request
Find the original repo's owner on Slack, and politely ask them to review your Pull Request. It is almost guaranteed that they will ask you to make changes (NOTE: if you are reviewing someone else's changes to your repo, please ask them to change something so they can practice this part, even if it's small).
When you are asked to make changes, go back to your code and make sure you are on the same branch that you submitted. For example, git checkout issue-5 to get on the issue-5 branch.
Edit the code to address the reviewer's comments. Make sure you deal with all of them! When you're done, add another commit to this branch:
git checkout issue-5
git add file1
git commit -m "Updating x, y, and z based on review feedback"
git push origin issue-5
Again, change issue-5 to whatever branch you are working on. Once you've done this, go back to the Pull Request on GitHub and leave a comment telling the reviewer you have completed all their changes, and what you did to accomplish them.
Repeat this cycle as many times as necessary for the project owner to Approve your changes and merge your work.
NOTE: if you are merging another student's work on your master/main branch, make sure you pull these changes into your local machine afterward (assuming you are working on the main branch):
git checkout main
git pull origin main
This will bring all of the new code changes into the repo on your local machine so that you can build on top of them. If you forget to do this, the changes will be included in your repo on GitHub but not in your locally cloned repo.
Also, make sure the original Issue gets closed once the Pull Request is merged. It might have happened automatically, depending on whether or not the original issue included the text Fixes #5 (or whatever the issue number is) in the description.
Step 9. Write a Blog Post
Write a blog post about the process of contributing a code change to another project. In your post, include links to everything you discuss (e.g., the project repo, your issue, your pull request). Discuss what you did, the changes you made for your feature, and the process of getting your work accepted. What problems did you have? What did you learn? What would you do differently next time?
If your repo received a pull request, please also talk about what it was like to get a submission. How much did you need the author to change? How did that process go?
Submission
When you have completed all the requirements above, please add your details to the table below.