Assignment 5 (Individual Assignment): PR for Open Source - Part A [100/100 MARKS]

The previous 3 assignments have exposed you to:

  • Analysis of user stories
  • Analysis of issues, branches, pull requests, and understanding how a repository works
  • Working as a team to complete a project with good issues, pull requests, communication, documentation and testing

This assignment builds on all all of these skills and exposes you to working on a real-life OSS repository.

This assignment is comprised of two parts:

  1. A report, answering the questions listed below, and
  2. A presentation detailing your work on the assignment. See the full details here Presentation.

Starting The Assignment#

Individually, take a look at all of the course recommended repositories listed here on this Google Sheet. Those are just suggestions, if nothing there interests you, you can also take a look at the Awesome for beginners repository and the Apache Projects Directory. Or, if you still don’t like anything, you can find your own repository to work on. If you do find your own repository, you will need to get approval from your tutor before you can start working on your assignment.

You must discuss with your tutor about which repository and issues you would like to work on. More information on this can be found in Activity 1. Please note that you will need to get approval from your tutor before you can start working on your assignment.

You CANNOT work on wyvernlang, however if this is something you are interested in, email Alex (alex.potanin@anu.edu.au) about it.

Activity 1 - OSS Project Selection [0/100 MARKS]#

Very carefully read the starting instructions here. See also checking with your tutor.

After discussing with your tutor about which repository and issues you would like to work on.

Selecting a Repository#

It is essential that you find repositories that are suitable for you to work on. You should be able to find a repository that:

  • Has good, well documented, and easy to follow setup/installation instructions
  • Is an active repository, with recent commits and issues. Avoid projects that have not been committed to or have any issues in the last 6 months or longer. Watch out for MIA maintainers! It only makes your life more difficult when you cannot get in touch with the maintainers of the project when trying to work on your assignment.
  • Is not too hard to follow or understand. You should be able to understand the codebase and the issues you are working on. It should also have clear goals and outcomes.
  • Is in a language that you are comfortable with. If you are not comfortable with the language, you do not want to have the additional burden of learning a new language, find something else. If you are unsure, stick with a Java project, or talk to your tutor.
  • Something you will enjoy working on. This is a taste of what it is like to not only work on OSS, but working in the real-world (kinda).

If you are unsure, talk to your tutor! They are here to help you after all.

How Do You Choose Issues?#

No two issues are created equal. It is up to you to choose an issue(s) you want to work on based on the following criteria:

  • Difficulty: How difficult is the issue? Is it a simple bug fix, or a more complex feature request?
  • Size: How big is the issue? Is it a small bug fix, or a large feature request?
  • Time: How much time do you anticipate needing to work on the issue?
  • Workload: How do you see the potential workload of the issue(s) you have selected?

If you are unsure, talk to your tutor! You can always change issues later on, but try and find suitable issues to start with to avoid having to restart or update your tutor with changes.P

How Many Issues Will You Need To Choose?#

This is up to you and your tutor to decide and come to an agreement. There will need to be evidence that enough work is present.

For example, selecting a single issue where you fix a couple spelling mistakes in a README file is NOT appropriate. However, you may choose to find another issue where you work to fix a bug within the codebase, and pick up the spelling mistakes one to go along with it if you want to have a bit more to talk about in your report. Talk to your tutor.

Checking with your tutor#

You will need to fill out this quiz on Wattle with your selected issue(s) after you have checked with your tutor - https://wattlecourses.anu.edu.au/mod/quiz/view.php?id=3011995. The quiz has unlimited attempts, just make sure to let your tutor know if you pick up more or less issues, or end up changing issues.

The quiz also asks you to provide very short answers to the How Do You Choose Issues? section above.

  • Difficulty: How difficult is the issue? Is it a simple bug fix, or a more complex feature request?
  • Size: How big is the issue? Is it a small bug fix, or a large feature request?
  • Time: How much time do you anticipate needing to work on the issue?
  • Workload: How do you see the potential workload of the issue(s) you have selected?

Your responses aren’t marked, just to show you have taken the time to analyse and think through your selected issues and that you have some understanding of what you are getting yourself into by selecting the issues you have.

Activity 2 - Working on the OSS Project [10/100 MARKS]#

An important update: Before starting work on an issue(s) you must first get in touch with the maintainers of the repository and get that issue assigned to you so that your work does not interfere with the work of another person. You can check assignees on the right hand side of an issue. Ideally there is no one assigned to it, if the issue is assigned to someone, but it has not been updated in a while, you can ask the maintainers if you can take over. Let your tutor know and we will deal with it on a case-by-case basis.

github-issue-assignees

With any codebase, it is vital that you are able to pull it apart and understand how it works. This is the first st/ep in being able to contribute to it. Figuring out and understanding what the issue(s) you are working on that someone has reported are, how they are triggered, and how to solve/fix them is a vital skill in being able to contribute to an OSS project.

  • You will need to work on understanding the codebase you have selected and what the issues you are working on consist of. Document your findings in the report.
  • Break down the issue(s) and understand what needs to be done to fix them at a high level.
  • Document the process, as described in Activity 4.
  • Your report must also include a screenshot of the email(s) you sent to your tutor, any follow ups if you changed issues, and all confirmations from your tutor.
  • A URL to the repository(ies) you are working on, URL to all issues selected.

Activity 3 - Opening and Submit a PR to the project [10/100 MARKS]#

After you have worked on the issues, you will need to open a PR to the project. Your tutor should take a look before you open any PRs. Try and avoid things like this, and try not to put too much of a burden on maintainers. It is not recommended to open PRs too close to the assignment deadline, but it will be a good learning experience.

If PR is accepted [5 Bonus Marks]#

If any one of your PRs is accepted into the project, you get a one off 5 bonus marks. The total mark for this assignment cannot exceed 100.

Activity 4 - Documenting the Process [50/100 MARKS]#

You will need to document your findings in the report, which will be submitted as part of your assignment. Some things (as a non-exhaustive list) include:

  • Document what the issue is, how it is triggered, and how you plan to fix it, go into the specifics of your implementation for each issue.
  • What relevant parts of the codebase are involved in the issue?
  • What was involved in opening and submitting the PR?

Some things you should consider explaining in your report (not an exhaustive list):

  • Can you explain all the relevant parts within the repository that relate to, rely on, are impacted by, or anything else by the issue you are working on?
    • What would solving this mean to the project?
  • Does your solution fit neatly into the rest of the project? Does it follow the conventions of the project?
  • Is it easy to understand what you have done/propose to do?
  • Are there edge cases / performance problems / other things that you (or they - the individual who opened the issue) have not considered/addressed?
  • Was there anything you could have improved on?
  • You can also use screenshots, external references, etc. to help explain your findings.

Activity 5 - Work/Consistency In the Repository [30/100 MARKS]#

You will be marked on your work within the repository you work on: do you follow the guidelines, standards/conventions, and contributing rules of the project? Do you make it easy for the maintainers to review and understand your work? Do you engage in discussion and other activities in a professional manner? Make sure it is easy for your tutor to see what issues you have worked on, and how you have contributed to the project. Add screenshots and links where possible so we can check.

In addition to the above, document and list where you found information regarding to any guidelines, conventions, or rules of the repository and anything else you deem necessary to back up why you might have approached something one way or another.

Keeping in mind that passing off work (regardless of if it is within your report, or from someone else in the GitHub Repository, or any other behaviour) that is not your own is a violation of the ANU Academic Integrity Policy. Make sure to reference anything you used within your report that is not your own work.

Activity 6 - Presentation#

See the Assignment 4 Presentation page for more information.

Submission Checklist#

  • Have fully read both this assignment page and the presentation page
  • Selected a good OSS repository to work on
  • Selected good issues to work on
  • Have filled in the quiz and recieved confirmation from your tutor to work on your selected issues
  • Workload is well suited to timeframe
  • Have documented your findings/fixes in the report

What is expected in this assignment?#

  • HD -> All selected issues have PRs, following documentation and instructions for PR and contribution in the project.
  • D -> All issues have PRs, documentation and instructions followed with exceptions or not enough justification.
  • CR -> Majority of issues have PRs, documentation and instructions may not have been followed or not enough work completed/documented.
  • P -> Some issues have PRs, and/or documentation and instructions not followed at all.
  • N -> No issues have PRs, and no documentation or instructions followed.

Submission Instructions#

FAQ#

bars search times arrow-up