Homework Assignment #6 — Contribution

In this assignment you will contribute to an open source GitHub project.

Your high-level goal is to produce and submit a non-trivial modification or extension to an open-source project in a way that maximizes the chances that the project maintainers accept it. If you demonstrate to us that your change has been accepted and integrated into the project’s code base, you will receive +6% bonus points on HW6b. You will select an open source project, select a change to implement, actually contribute to the project, report on your insights, and reflect on your distributed software engineering experience.

You may work with a partner for this assignment. If you do you must use the same partner for all sub-components of this assignment. Use the partner selection feature on Gradescope. Only one partner needs to submit the report on Gradescope, but if you both do, nothing fatal happens.

Task Selection

You will select an open-source GitHub project and complete one or more bug fixes or extensions within it. For the rest of this assignment, we will collectively refer to bug fixes and extensions as tasks. You have considerable freedom in which project and tasks you choose, so long as they adhere to the following criteria:

If you have questions on these criteria, contact the course staff (particularly the TAs). We strongly recommend that you interact with the course staff during this process to verify that the scope of your proposal seems reasonable. We strongly encourage you to do this as early as possible, and before you start investing too heavily in your plans.

A great way to do this is via office hours or during discussion sections.

Once you have settled on a project and one or more candidate tasks, research your ideas in more detail. Read the documentation. Build and execute the source code, and try to read and understand it. You should explore the code to the point that you understand how your modification fits in the overall picture. You should be convinced that it is both non-trivial but also doable with the resources (time, team members) available.

In selecting a task, consider the functional and non-functional implications and requirements, as well as how it fits in to the larger project structure.

See the end of this document for hints on task selection from students in similar classes at other universities. You might also consider a website such as up-for-grabs.net which lists GitHub repositories with beginner-friendly labels (special thanks to J. Kollin and P. Shultz for this recommendation).

Task Planning

You should plan before you start coding. This includes identifying risks and requirements and developing a schedule. If you are working with a partner, you should also solidify a collaboration plan.

Performing the Task

Implement the selected task. You should write code and perform adequate quality assurance activities. Beyond that, you will likely also need to:

You are required to submit your work to the open-source project using your real identity. It is not required that the project accepts your submission, but you will get bonus points if they do.

Keep track of how you actually spend your time while you are performing the task. The final report requires you to submit a "what actually happened" schedule.

HW6a — Task Selection Report

The first deliverable is an initial report on the project and task(s) you select, including a proposed schedule (with effort estimates).

Start by researching candidate open source projects. Make an informed decision about which project you will contribute to. As examples, consider: the type of software, the project age, the number of active contributors, the amount of activity and communication among contributors, the number and types of feature requests/bug reports you might address, the tools and mechanisms the project uses to communicate and collaborate, the dominant programming language/paradigm/framework, as well as the larger context in which the software operates. Communication with the candidate open source projects is encouraged.

Your goal is to to make a principled, informed decision as to which project and task(s) you will tackle. The type of information you collect can vary depending on you make this decision. However, you should justify that decision by grounding it in facts about the projects and tasks you consider.

You are required to choose a project hosted on GitHub. (This artificial constraint simplifies our grading process. If a project is hosted on GitHub in any way and is also hosted elsewhere, it counts.)

Your report should include:

  1. Names and email ids. You must include your name and UM email id (e.g., "weimerw"). If you have a partner, you must include the partner name and email id as well.
  2. Overview and justification. A report on the project you selected, summarizing the relevant characteristics you considered when making your selection. Beyond whatever additional information you collect in your research, include at least a name, a website link, and a brief description of the project (what it does, who uses it, etc.). Explain the criteria you used in selecting it over any others, referencing the collected information from your overview. You may contrast it to other projects you considered but rejected, if applicable. (Approximately 2 paragraphs.)
  3. Successful build. Evidence that you can build and run the software (e.g., a screenshot or text output from a successful build, a screenshot of the running program). Getting an open-source project to build and run can be a huge effort, and we want to mitigate this risk.
  4. Task(s) description. A brief textual description of your proposed task(s). In the likely event that you are proposing to tackle several tasks, list each one and give a priority order. Depending on how difficult the issues end up being, you may do not necessarily have to implement all of them. In the final report submission HW6b for you will have a chance to indicate how your actual activity deviated from this prediction. (About, or up to, 2 paragraphs per task.)
  5. Task link(s). Evidence that the task(s) is/are requested by the community (a screenshot or issue tracking link suffices).
  6. Requirements. A description of each task's requirements, both functional and quality. Document these requirements at whatever level of detail you consider appropriate: use cases might be helpful, for example, but are not required. You might consider how your proposed task fits into the overall goals of the project. We do not want any sort of full formal software requirements specification. Instead, we want lightweight documentation of your task's requirements and evidence that you understand how they fit into the larger project. (At most half a page per task.)
  7. Initial time plan. Choose any format as long as it is clear (e.g., Gantt diagram, plain text). This should include at least: individual tasks and milestones, with deliverables; estimated effort for each task; dependencies between tasks; and a best-effort assignment of tasks to team members. We encourage you to include supporting evidence for your estimates. We will grade you on the presence of your planning but not its accuracy; it is completely acceptable if plans change. Be sure schedule time for QA activities. See the final team report for more on QA.  (At most one page.)
  8. Short risk assessment. Identify and briefly describe key risks in each task and discuss how you plan to mitigate those risks. (1 paragraph, or 1 paragraph per task.)
  9. Initial process plan. Describe the process you plan to follow. This should mention quality assurance and how you plan to communicate and collaborate as well as divide and integrate work. (At most half a page.)
  10. Task scope justification. Evidence that the tasks are of a sufficient and reasonable size and complexity (for your or your team) and for this assignment. You may want to review the task scope bullet point under Task Selection and the Plan Updates bullet point under Project Report for ideas about what to include here. (1 paragraph per task)

Via Gradescope, submit the PDF report for HW6a. There is no explicit format (e.g., for headings or citations) required. For example, you may either use an essay structure or a point-by-point list of question answers. The task selection report is worth 20 points and is graded holistically, with approximately equal weight given to each of the items above.

Advice From Former Students

Read what former students say about Homework 6a and project selection.

HW6b — Project Report

After completing and submitting the modification, write a report about the tasks you have performed. The report will include a description of the project and its business context, a description of your tasks and their context, an explanation of deviations from your plans (in HW6a), and a discussion of your quality assurance efforts and why they were suitable. Specifically, your report should cover:

  1. Names and email ids. You must include your name and UM email id (e.g., "weimerw"). If you have a partner, you must include the partner name and email id as well.
  2. Selected project. A brief description of the open source system to which you contributed (1 paragraph). You may reuse text from Part A.
  3. Project context. An analysis of the open-source project's context and "business model". This may include a short history of the project, competing open- and closed-source projects, or a discussion of the developers' motivations to build this system. Essentially, we want to know why this project exists and why it is important. (At most one half page.)
  4. Project governance. Describe the processes and tools the project uses to communicate coordinate among contributors. Are these processes formal or informal? Provide an explicit description (possibly with a diagram) of the acceptance process used for efforts like the task you completed. If applicable, include standards or expectations regarding software engineering activities including requirements, design, and quality assurance. Alternatively, mention that no such standards exist. (Usually about one page; length varies.)
  5. Task description (per task). A description of the tasks you have implemented and a high-level description of how you implemented them. (At most one half page per task.)
  6. Submitted artifacts (per task). Evidence of the code, documentation, test cases, and/or other artifacts you produced for the task, and evidence that you submitted them to the project. We require links to publicly available resources (project repository, email archives, pull requests, etc.). Each such link should be accompanied by a brief description.
  7. QA strategy. Describe which QA activities you performed and justify why you selected these QA activities over others. Describe metrics if appropriate. The justification will likely refer to relevant requirements as well as to the project's practices. (At most one page.)
  8. QA evidence. Evidence of your quality assurance activities and an associated description or argument. Evidence might include source code, links to source code of tests, test results, comments from code reviews, reports from static or dynamic analysis tools, links to or screenshots from a continuous integration platform, and so forth. For example, you might use Travis CI, which supports continuous integration testing for GitHub, and link to a CI build in your report (see examples below; while neither required nor sufficient, Travis CI evidence is particularly easy for the course staff to evaluate).
  9. Plan updates. A description and justification of deviations between your initial plans and your performed activities, if any (there are almost always a few). Changes are expected, but they should be tracked and explained. Describe changes in scope (e.g., fewer tasks) and in the schedule and work allocation. Provide an after-the-fact "what actually happened" schedule and note differences. Explain the causes of the changes, such as unanticipated risks. (At most one page.)
  10. Your experiences and recommendations. Summarize your experiences (and what you learned!) interacting with this community of open source developers, focusing on any surprising or unusual aspects of the process or interaction. Did you run into any trouble understanding, changing, or contributing to a large, pre-existing project? Were there unanticipated challenges in either implementing your change or in getting the change submitted to, and accepted by, the project maintainers? Did the project collaboration process or culture help or hinder your effort in any way? Characterize any interaction you had with the team leadership and community. Highlight any useful (or useless) input you received. In addition, describe any changes you would make if you were starting a new project from scratch. What worked here (and why), what did not work here (and why), and what would you do instead? You may (but are not required to) also relate the experience from this homework assignment with relevant experience from internships or other projects. (Two or three pages. This is the heart of your report. Convince us that you integrated course concepts and learned something.)
  11. Advice for future students. Give a single sentence of advice to students taking this class in future semesters. This advice can either be about HW6 or any other course aspect. What do you wish you had known earlier? Any non-empty answer counts. We will display such advice anonymously on the webpage for next semester. If you are working with a partner, each of you should give a separate single sentence. If you are willing to let future students see your materials (cf. the examples at the bottom of this webpage), indicate as much in your report.
  12. Optional extra credit. Evidence that at least one of your changes has been accepted into the code base of the open source project. You receive the extra credit if more than zero of your changes are accepted (so 1, 2, and 500 accepted changes all get the same extra credit). This typically takes the form of links or screenshots or associated pull requests and commits. Because of grading logistics, any acceptance must be done by the time you turn in the report; we cannot retroactively award points if they accept your changes just a few days later. (Suggestion: start early!)

Hint. Consider all of the topics we covered in class (for example, glance over the list of lecture topics from the syllabus). They are all fair game here. In addition to the "academic" topics, you should also feel free to compare and contrast your experiences with, or bring in insights from, any of the optional readings or guest lectures. Impress us.

Via Gradescope, submit the PDF report for HW6b. There is no explicit format (e.g., for headings or citations) required — but this is your final report for this class, so you are encouraged to make it look professional. The project report is worth 50 points and is graded holistically. If you provide evidence that your changes were accepted by the maintainers, you will receive +3 points (i.e., 6%) on HW6b.

The report should be single-spaced.

Advice From Former Students

Read what former students say about Homework 6b.

Submission

Submit the two reports via Gradescope. (Note the two different due dates.)

Commentary

This style of final project is popular with top-tier software engineering programs. For example, a very similar assignment is the final homework in Carnegie Mellon's Software Engineering elective (15-313); indeed, this assignment is adapted from that one.

Learning goals include, but are not limited to:

Examples of Task Selection and Project Reports

Some students who took EECS 481 previously graciously agreed to allow their final reports to be made available as examples. You can use these to get examples of all aspects of the assignment, including project selection, task selection, QA, and communication. Note that some students report that they wished they had chosen different projects: read carefully. In addition, look carefully at whether or not a project was a group or solo effort, as well as whether or the goals were completed — such information can serve as a helpful guide in your own task selection.

(For various reasons, including FERPA, no information is, or will be, given or implied about the grades associated with these examples. If you are concerned about your own grade, you might try to do at least as well as what you perceive to be the best example for each question. Some examples are strong in one area and weak in another.)

We also make available the names of projects used by students from the Winter 2018 offering of this class:

Overall, the most popular project to select was Microsoft's VSCode; other popular choices included Arrow, Atom, and Zulip.

In addition, a similar class at another institution has graciously shared the issues tackled by some students. Note that this other class covered slightly different topics and had a different reporting and grading struture, so you cannot directly conclude whether or not the students "did well" based on these anecdotes. Both positive-appearing and negative-appearing examples are presented.

If you are concerned about size, take issues comparable to those listed below until you have hit the hour guidelines given above. If you are concerned about quality, you are encouraged to do as well, in each area, as the best of each of these examples.

With one exception, each single issue below corresponds roughly to a "small task".