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. 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
work with a partner for this assignment. If you do you
must use the same partner for all sub-components of this assignment. Only
one partner needs to submit the report on Canvas, but if you both do,
nothing bad happens.
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:
- The open source project should be active, with many contributors.
Previous students have lamented choosing dead or maintenance-mode-only
projects without sufficient community support. We recommend that you avoid
- The task(s) should be taken from a bug report or feature request in a
public database or message board, following whatever protocol the project
uses to communicate and track open issues. Do not invent a task. Address an
actual, documented, already-existing project need.
- The task must require changes to the project's source code. Pure
documentation or design tasks are not appropriate.
You may choose one large task or several smaller, related tasks. (If you
are working with a partner, choose twice as much.) Choose
tasks that benefit from teamwork and are appropriate for your team size
(i.e., do not select one small independent task per team member). The tasks
should be scoped such that each team member spends ~24 hours each on the
project: ~7 hours to identify a project and get the lay of the land; ~12
hours to create a work list, design, and execute your changes; and ~5 hours
to reflect and prepare your report.
- Hint 1: Read this entire homework description and pick a project that
will give you something detailed to talk about in each of the required
report sections. For example, part of the final report is a discussion of
how the project members communicate and accept changes. While most projects
have informal, rather than formal, processes, a small project with none at
all may be difficult to write about.
- Hint 2: Students often report that this project makes a great
talking point at technical interviews, especially with higher-tier
companies. You may want to select a slightly more ambitious task so that
you can "show off" later. (It is tempting to think of "ambition" solely in
terms of the complexity of the task, but perhaps employers care more about
the size of the code base, the number of active developers, the rigor of
the development process, the scope of the testing and QA, the use of
analysis tools, the adherence to a required project design or architecture,
and so on.)
If you have questions on these criteria, contact the course staff. 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
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)
In selecting a task, consider the functional and non-functional
implications and requirements, as well as how it fits in to the larger
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:
- Take further steps to understand the project's code. You might find it
useful to discuss or make use of available diagrams, documentation,
and analysis results.
- Submit your changes to the project. Create any necessary documentation to
enable acceptance of your code. New contributors rarely have commit
privileges to a master repository. Common contribution mechanisms include
pull requests, emails to a project lead, or discussion board posts. You may
also need to update the bug database.
- Plan and perform an appropriate level of “marketing” for your submission.
Avoid stepping on toes and keep your activities appropriate for the project
culture. Try to mimic contributors who have previously successfully
submitted similar work.
- Solicit feedback and respond to those who take the time to evaluate your
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"
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
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:
- 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
- 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.
- Task(s) description. A brief textual description of your
proposed change(s). If you are proposing several changes, list all
proposed changes and a priority order. Depending on how difficult the
changes end up being, you may do not necessarily have to implement all of
them. However, if your actual changes deviate from the plan, we expect a
short explanation with your final submission. (About 2 paragraphs per task.)
- Task link(s). Evidence that the task(s) is/are requested by
the community (a screenshot or issue tracking link suffices).
- 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.)
- 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.)
- Short risk assessment. Identify and briefly describe key
risks in each task and discuss how you plan to mitigate those risks. (1
- 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.)
- 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. Your scheduling and effort estimation, below, may
be used to help justify your argument here. (1 paragraph per task)
Via Canvas, 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.
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:
Selected project. A brief description of the open source system to
which you contributed (1 paragraph). You may reuse text from Part A.
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.)
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.)
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.)
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
- 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.)
- QA evidence.
Evidence of your quality assurance activities.
This 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.
- 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.)
- 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
(Two or three pages. This is the heart of your report. Convince us that you
integrated course concepts and learned something.)
- 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.
- 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.
- Optional extra credit.
Evidence that your changes have been accepted into the code base of the
open source project. 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!)
Via Canvas, 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%).
Submit the two reports via Canvas.
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:
- Holistically apply software engineering methods in the context of a
real-world problem, including process, requirements, design,
measurement, quality assurance, and coding.
- Gain an integrated understanding of the defect report (or feature
request) lifecycle by addressing a real-world issue.
- Understand how distributed development (teamwork) and productivity
operate in a non-classroom setting.
- Gain broad and deep exposure to the culture and practices of
open-source communities. Engage with an open-source community.
- Identify process issues and suggest improvements in real-world projects,
including communication, collaboration, tooling, quality assurance, formal
and informal rules and policies.
- Coordinate within a team and adopt practices for efficient teams.
- Understand a project’s architecture and design and use that to inform
decisions about coding a resolution to a task.
- Divide and schedule work within a project. Gain concrete experience
with effort estimation.
- Observe and interact with an active quality assurance process.