Assignment 5 (Group Assignment): PR for Open Source [100/100 MARKS]

The previous 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 Group Presentation.

Starting The Assignment#

As a group, 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.

We generally want to avoid research projects or ANU projects. For example, 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?#

There will not be any set number of issues your group has to take on. This is up to you, your group, and your tutor to decide and come to an agreement. There will need to be evidence that enough work is present for your group size.

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=3291439. 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: Ideally, 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.

HOWEVER, some repositories can be inactive and some maintainers can be busy with their own work. Please do not wait too long and do not burden the maintainers with any follow up - simply 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.

  • Either individually, as a pair, or in some other arrangement within your group, 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.
  • You should be committing your proposed changes to the repository you are working on after it has been reviewed by at least one other member of your group. Try and spot any issues within your proposed commits to ease the burden placed on the maintainers of your selected project. Take on any feedback from your group members, and ESPECIALLY any feedback from the maintainers of the project you are working on.
  • 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.

To work on the repository, it is recommended that you fork the project so that you can work on your selected issues and still show history of work, even in the event the issue in the repository is closed. You can then submit a pull request to the original repository to merge your changes into the main codebase when you get to that stage.

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, after discussion with your group, and at least the majority of your group has taken a look at it. 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. Again please do not bother the OSS maintainers who may be overwhelmed with requests and treat this as a lightweight bonus only.

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.

It is ESSENTIAL to clearly label your work within the report, who you worked with while working on the issue(s), what they contributed, and any other supporting information. You must also include a section reiterating and matching up each group member to a GitHub username.

Each issue your group works on must have a paragraph or two explaining how you contributed, who you worked with, and what they did. Be very specific and exhaustive. You are encouraged to work freely with all group members even if you are not working on the same issue, or have split up within your group. Discuss, review, and work together to improve your understanding of the codebase and the issues you are working on, especially if there is something you don’t understand.

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 - COMP6210 Students ONLY#

You will need to submit in Wattle an individual essay of around 1000 words that will be worth 20% of your mark for this Group Assignment (the other 80% will be as per the above instructions - the same as the COMP2120 students).

In this short essay we want you to reflect on the different licenses used in the open source applications (look at the slides for week 12 that lists the most commonly used licenses). These can also be found here.

For the open source project you contributed to, which license did it use and did you consider it appropriate for its goals. Discuss and justify your reasoning.

Read the following research paper from ICSE 2017 (International Conference on Software Engineering - the top venue in software engineering):

It discusses automatic detection of FOSS license violations. Explore any other related work on the subject by either following the citations of the paper “back in time” or searching for papers that cite this paper in their references “going forward in time”.

Discuss the work in this field of automatic detection of open source license violations and discuss where this work may lead to in commercial settings in your personal opinion. –>

Activity 7 - 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