-
Notifications
You must be signed in to change notification settings - Fork 0
lab 1
Friday September 12th 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.
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 Teams 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
Use MS Teams 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 Teams that you're looking for a partner.
Each student needs to:
- complete enough of Release 0.1 to get something reviewed (does not need to be finished)
- find a partner in the class via Teams to collaborate with on this lab
- review, test, and file GitHub Issues in your partner's project repo
- have another student review, test, and file issues in your project repo. 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; however, it's fine if multiple people work on the same repo, too.
- fix and close all issues filed by your reviewer
NOTE: even if your Release 0.1 code isn't perfect (no code is ever perfect!), or isn't finished, you can still have someone review and test it. Software is never done.
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.mdfile (make sure it has one!) to set up the project on your machine - follow the
README.mdinstructions to run the project in various ways - read the code from start to finish, see below.
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 need each other's help to do it well.
Use GitHub Issues (async communication), Teams (sync text/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 the problem.
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 (name, year, etc)? -
Does the
README.mdexist? 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 allow working with the current directory? What if you give no path (does it assume the current directory)?
-
What happens if you pass a folder name?
-
What happens if you pass two file names?
-
What happens if the filename has a space or another special character in it?
-
Does the output go to
stdout? -
Do log messages and errors go to
stderr? -
Does the tool generate the expected output?
-
Could the output be improved in any way?
-
What happens if you pass a folder that contains a large file, or a filename that points to a large file?
-
Does the tool provide useful error messages when things fail? Is there any information or formatting you could add that might improve this?
-
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. -
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 4 or 5 issues minimum for a project this size. Issues can and should be small and focused on a single thing. Software is never finished, and can always be improved.
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.
Tip
Testing and code review is about helping us write the best software possible. Don't take criticism personally, use it as a chance to grow. 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.
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.
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?
Whenever possible, your blog post should contain links to the things you discuss (repos, issues, people, etc).
For this to work, you're going to have to leverage your community. Teams 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 Teams and GitHub; don't wait for people to find you.
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.