lab 1 - humphd/topics-in-open-source-2024 GitHub Wiki
Lab 1
Due Date
Friday September 13th by midnight.
NOTE: this lab requires you to have completed some of your Release 0.1 before you can continue. However, your Release 0.1 does not need to be completely finished before you do this lab.
Overview
So far your Release 0.1 has been an individual project. Lab 1 will change that so you begin working on the code in a community. This lab will help you practice the following:
- using Slack to network and collaborate with community members
- learning how to "release early, release often" vs. waiting for a project to be "perfect"
- thoroughly test and review code you didn't write
- identify bugs, missing features, and other issues in a GitHub repository
- file useful GitHub Issues
- have the open source community test and review your own code
- collaborate with the wider open source community on GitHub
Step 1. Networking on Slack
Use Slack to find a partner for this lab (you can work with many different people in the course, you don't have to be partners forever) to review and test your Release 0.1 code. You can work with anyone in the course, just let people know in Slack that you're looking for a partner.
Each student needs to:
- complete enough of Release 0.1 to get something reviewed
- find a partner in the class via Slack to collaborate with on this lab
- review, test, and file GitHub Issues in your partner's project
- have another student review, test, and file issues in your project. You can review/test the code of the student who reviews/tests yours, or you can work with another student (i.e., you don't both have to be each other's partner). If someone has already reviewed/tested a particular repo, move on to one that hasn't been reviewed/tested yet.
- fix and close all issues identified by your reviewer
NOTE: even if your Release 0.1 code isn't perfect (no code is every perfect!), or isn't finished, you can still have someone review and test it. Software is never done.
Step 2. Review and Test
Each project needs to be reviewed and tested by another student. This means doing each of the following steps, and keeping track of what does and doesn't work, what is and isn't clear, etc:
- find and fork the repo on GitHub
- clone the fork locally (i.e., to your own machine)
- follow the instructions in the project's README.md file (make sure it has one!) to set up the project on your machine
- follow the README.md instructions to run the project in various ways
- read the code from start to finish, see below.
Step 3. Review and File Issues
You are asked to do a detailed review of the project and its code. NOTE: this is not a review of the developer, only the code. Reviews should help developers, and their software, get better, and aren't meant to belittle or make people feel small or incompetent. Use this process to encourage and collaborate with one another. Remember: writing software is HARD, and we all need each other to do it well.
Use GitHub (async text), Slack (sync text), or Teams (sync audio/video/screenshare) to discuss things as you work with your partner. For each problem, bug, or improvement you find, file a GitHub Issue in the original repo. Make sure your issues are clear and include enough information to be useful. A good issue has both a concise Title and also a thorough Description with text, screenshots, screencasts, etc. to help the developer understand.
Here are some suggestions of steps to take and actions to test, but you are welcome to add more:
- Does the project have an appropriate open source
Licensefile? Is the copyright and license information done correctly? - Does the
READMEexist? Is it clear? Could any info be added to help improve the documentation? Was any of the information wrong? Was any information missing or assumed? - Were there any mistakes in the README (typos, errors, formatting)? Was proper Markdown used?
- Did you have any problems doing the setup, installing the necessary dependencies, etc (version issues, OS issues, etc)?
- Does the
-vor--versionflag print the tool's name and version? - Does the
-hor--helpflag print a useful help message? Could the help message be improved? - Does the tool accept a file path and process the file correctly?
- What happens if the filename has a space or another special character?
- Does the output go to
stdout? - Do log messages and errors go to
stderr? - Were any secrets (e.g., API Keys) included in the repo?
- How well did the LLM integration work? Did the program use the LLM effectively to transform the input? Did you run into weird cases? What was your input data when that happened, and what was the output you received vs. what you expected?
- Are at least 2 optional features implemented? Are they discussed in the
README? Do they work as expected? Can you break them with various input or steps? List those steps/input in your issue. - Does the program work the way you expect? Was anything surprising?
- Does the program work correctly? Could anything be improved?
- Was anything else missing?
- Did you notice any issues while reading the source code? Are there formatting issues? Could the code be cleaned up? Is it using any incorrect or inefficient methods? Are there better ways to write any of it? Make detailed suggestions in your issues to show how you'd improve it. Saying "this is not good" isn't helpful or enough. Explain why and make suggestions about how to improve.
- Was the code easy to understand? Could it be simplified?
- Were any parts of the code overly complex? Could they use a comment to help document what's going on?
- Are there any features that are missing that you think other users would need?
- Finally, what did you like about the code and/or project? Did you learn anything while reading and testing the code? Make sure your feedback discusses this along with any bugs.
If you get to the end of Step 3 and can't find any Issues to file, start again and try harder! I expect each reviewer to file at least 3-5 issues for a project this size (they can be small). Software is never finished, and can always be improved. Remember: an issue can (and ideally should) be very small.
Step 4. Have Your Project Reviewed and Tested
The same way that you reviewed and tested another student's repo for Steps 2 and 3, have another student review and test yours. This can be the same person that you reviewed, or someone else. Support them as they do it, answering any questions they have as they work.
Remember: testing and code review is about helping us write the best software possible. Don't take criticism personally. Everyone gets their code reviewed in open source, and it's normal that you will make mistakes. There's nothing wrong with you if someone finds a bug in your code, or suggests ways to improve things. This is how we build high quality software. You're not a bad programmer if you make a mistake: we all make mistakes. Accept your reviewer's feedback as something meant to help your project get better.
Step 5. Fix Your Issues
After your code has been tested and reviewed, take some time to fix your issues before submitting Release 0.1. You are free to fix your code yourself, or submit fixes to the project you review. We'll focus on Pull Requests next week, so it's not necessary this week, if you're not feeling ready.
Once you fix the Issues your partner filed on your GitHub repo, comment on them and close them.
Step 6. Blog About the Process and Outcomes
When you're finished Steps 1-5, write a blog post. In your post, talk about the following:
- How did you go about doing your code reviews? Do you prefer an async or sync approach? Why?
- What was it like testing and reviewing someone else's code? Did you run into any problems? Did anything surprise you?
- What was it like having someone test and review your code? Were you surprised by anything?
- What kind of issues came up in your testing and review? Discuss a few of them in detail.
- Provide links to issues you filed, and summarize what you found
- Provide links to issues that were filed on your repo, and what they were about
- Were you able to fix all your issues? What was that like?
- What did you learn through the process of doing the testing and reviewing?
Getting Help
For this to work, you're going to have to leverage your community. Slack will be a critical tool for us all this week, as we try to find others to work with, run into problems, and need help. Be vocal on Slack and don't wait for people to find you.
Submission
When you have completed all the requirements above, please submit your work by add your details to the table below.
NOTE: in order to edit this wiki, you must accept the GitHub invitation you were sent for this repository. If you don't have one, please talk to your professor.