-
Notifications
You must be signed in to change notification settings - Fork 1
lab 1
Friday September 15th by midnight.
NOTE: 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 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 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 TIL 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:
- 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.
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 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. Reviews should help us, and our software, get better, and aren't meant to be a tool to belittle or make people feel small or incompetent. Use this process to encourage and collaborate with one another.
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 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? - Was the
READMEclear? 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 tool accept a file path and process the file correctly?
- Does the tool accept a folder path and process the file correctly?
- What happens if the filename has a space?
- 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 have the expected name? - Is the generated
.htmlfile located in atil/folder? - Does the
til/folder get deleted and recreated on each run? - 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?) - 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?
- 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 5 issues for a project this size. Software is never finished, and can always be improved. Remember: an issue can (and ideally should) 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 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.
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 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.