lab 1
Friday September 17th.
NOTE: your Release 0.1 does not need to be completely finished before you do the 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 Slack to network and collaborate with community members
- 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 Slack to find a partner to review and test your Release 0.1 SSG code.
Each student needs to:
- review, test, and file issues for someone else'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. 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, 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 README.md file 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.
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. Review should help us, and our software, get better, and isn't meant to be a tool to belittle or make people feel small. Use this process to encourage and collaborate.
Use Slack to discuss things as you work with your partner. For each problem, bug, or improvement you find, file an Issue in the original GitHub repo. Make sure your issues are clear and include enough information to be useful. Here are some suggested steps to follow, but you are welcome to add more:
- Does the project have an appropriate open source License file? Is the copyright and license information done correctly?
- Was the README 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 installing the necessary dependencies (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
-ior--inputallow a file path to be processed? - Does the
-ior--inputallow a folder path to be processed? - Does a folder path find all the
*.txtfiles? Does it properly skip/ignore other types of files? - Is an
.htmlfile generated for each*.txtinput file? - Does the generated
.htmlfile contain the correct data? - Is the formatting, markup, structure, etc. of the generated HTML file correct. Is it valid? Test it at https://html5.validator.nu/
- Do the paragraphs in the
.txtfile get converted to<p>...</p>tags in the.html? Does this process have any bugs (e.g., what if you modify the source.txtfile, can you break it?) - Is the generated
.htmlplaced in a.dist/folder? - What happens if you run the tool twice, is the
dist/folder removed/recreated? - 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? Were 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 enough. Explain why and make suggestions about how to improve.
- Was the code easy to understand? Could it be simplified?
- 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, try harder! I expect each reviewer to file at least 3-5 issues for a project this size. Software is never finished, and can always be improved. Remember: an issue can be very small.
The same way that you reviewed and tested another student's repo for Steps 2 and 3, have another student review and test yours. 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 make or 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 you.
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.
When you're finished Steps 1-5, write a blog post. In your post, talk about the following:
- How did you go about finding someone to work with?
- 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 the testing and review? Discuss a few of them in detail.
- Provide links to issues you filed, and discuss 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?
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.
When you have completed all the requirements above, please 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.