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.
Project and Task Selection
Open Source for Social Good
Starting in 2021, students may consider open source projects
for Social Good (SG). Social Good is a broad term that refers to
projects that provide some societal benefit — for example,
projects that inform you about polling locations, or
availability of welfare services. We are interested in using the
results of your reports as data for ongoing research in software
engineering for social good, particularly as a result of the
pandemic.
You are not required to choose a SG project. However, if you are
interested, there are a few resources available for helping you
identify projects for Social Good.
You can refer to this list of
potential projects for Social Good, if you are interested. This
list contains the GitHub owner and repository name of the
project, as well as the corresponding goal of that project. This
list was developed as part of an investigation into projects for
Social Good. If you are interested, you can read
a paper
published by Huang, Ford, and Zimmerman in 2021.
In addition, the following two resources are available for
you to help find a Social Good project:
- Ovio: https://ovio.org/projects. Ovio has developed an
interal list of SG projects. (Use the "Topics" dropdown to
filter projects you are interested in.)
- Digital Public Good Alliance: https://digitalpublicgoods.net/registry/.
DPGA uses the 17 Sustainable Development Goals to indicate good
topics for SG topics for projects. Note that not all of the
projects listed by the DPGA are available on GitHub. You must
select a GitHub project for HW6.
You must 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 (subject to a
few requirements and recommendations), however, you should adhere to the
Golden Rule of Project and Task Selection:
Golden Rule of Project and Task Selection
The Golden Rule of Project and Task Selection is to read the
entire HW description, which includes HW6a and also HW6b,
and keep in mind what you will have to write in your reports later. Your
grade is based solely on those reports. Do
not pick a project or a task that will make it difficult for you
to complete any of the reporting obligations. If you are at all
uncertain, do not pick that risky project or task and instead pick
another where there is absolutely no doubt. A very common source of
student uncertainty or unhappiness is realizing, near the due date, that
a project or task that was not technically against the rules will make it
very difficult for you to present all of the evidence required to get all
of the points for HW6.
It can be very tempting to pick a non-standard project or task, such as a
project that does not involve any humans, or does not do any
testing, or does not use any code, or that is entirely a GUI or
front-end, or that only involves adding data to a database or repository
(and not actually programming),
or that is actually a textbook instead of a program, or
something like that. Do not pick that project or task. Instead,
pick a standard project or task. You can always go back later (e.g.,
after this semester) and work on the unique project, but to be able to
grade everyone fairly, we need to enforce standards for this homework
assignment.
Requirements and Recommendations
The following aspects of project or task selection are firm requirements
and cannot be waived. If you found a project or task that seems really
great but does not satisfy one of these rules, you must regretfully pick
another instead. Requirements:
-
With regard to task scope, the tasks must be scoped such that each team
member spends at least ~24 hours each on the project.
(For example, this might be ~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.)
- Note that these times are minimum requirements. You are
expected to spend this amount of time and also complete the reports
required below. Depending on the task you pick, it may take a bit more
time, which is fine.
-
You may choose one large task or several smaller 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
— do not select one small independent task per team member.)
- It is entirely acceptable to list a number of tasks and indicate
that you will stop after a few if you have spent the requisite amount of
time and have all of the required reporting material.
- Similarly, it is acceptable to list a large task and subdivide it
into smaller activities, indicating that you will stop after you have
spent the requisite amount of time and have all of the required reporting
material. (Note that it is easy for students to mess up here by working
depth first: you may need to work breadth first to ensure that you cover
all of the reporting elements.)
- The task(s) must 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. (Both the project
as a whole, and the particular issue(s) you choose, must be public on
GitHub. The graders need to be able to see them.) Address an actual,
documented, already-existing project need.
- You may pick a project, project type, or task type with which you
have previous experience. Some students leverage their previous expertise
to make this easier, some students push in new directions to ensure that
they learn more. Both are perfectly acceptable.
- You must pick exactly one project per team. Even if your team
has two people, you must restriction attention to exactly one project, not
two or more at the same time. All of your tasks must come from the same
single project.
- You may not pick a project owned or managed by yourself or
another UM student. (You may pick a project managed by a non-student
organization at UM, like ITS.)
You may not be involved in the genesis of the
bug report or feature request in any way. Do not invent a project need or
create your own. Similarly, you may not knowingly pick an issue created by
another Michigan student or have your code reviewed by another Michigan
student. If you know a maintainer of the project, or otherwise have a
conflict of interest, you must pick issues that were posted before
the start of the semester.
- You must not choose the Hedy project. A large influx
of 481 students has caused difficulty for this project, and we require
students to avoid it. (In future semesters there may be other projects
added to this exclusion list.)
- You must email (or otherwise reach out to, including via
Discord or other channels) a maintainer of a smaller project.
This is not necessary
for larger projects (such as VSCode) but you may still do
so. If you are not certain, do so. We recommend indicating that you are a
student in a course, that you hope to be working on the project for the
next few weeks, and that you'd appreciate any information on how you might
help. (Project maintainers have reached out to course staff requesting
this: on the one hand, they quite appreciate having students work on their
projects and improve them. On the other hand, they are better able to
manage multiple contributors and organize relevant issues if they know
about student participants in advance.)
The task must require changes to the project's source code. Pure
graphical, documentation or design or tasks are not appropriate.
In addition, there are a number of very strong recommendations
that you almost certainly should follow. While you are officially allowed
to disregard these recommendations, doing so will almost certainly result
in a lower grade because you will not be able to provide sufficient
evidence for all of the reporting obligations for HW6a and HW6b. See
the "Golden Rule" above. Recommendations:
- The open source project almost certainly should be active, with
many contributors. (If you are not certain, you can use statistics on
GitHub to compare across various projects.) Previous students have lamented
choosing dead or maintenance-mode-only projects without sufficient
community support. We recommend that you avoid that mistake.
-
The task almost certainly should not
be to implement an algorithm or data structure or to
provide an implementation of a "leetcode" or "hackerrank" or
interview-style problem (such as in a project like The Algorithms or Algorithms).
Pure-algorithm projects rarely result in enough evidence that
you have mastered requirements elicitation, code comprehension and
dependent coding within a large code base you did not write, since the
requirements for the algorithm are too direct and the code you write fits
into a separate, isolated container.
You may definitely pick a "normal" task for which you happen to choose to
use an algorithm or data structure as part of the solution, but you should
not pick a "textbook" or "education" task for which the algorithm source
code, itself, is the prime focus.
-
The task or project almost certainly should not
be a "pure frontend" activity that involves no testing. Such activities
rarely result in enough evidence that you have mastered aspects of
quality assurance. For example, most "standard" tasks will involve
both testing results and also code review activities. If you pick a "pure
frontend" task that does not admit testing and only involves code review,
you will not be able to describe as much as other students in your HW6b
report.
-
The task or project almost certainly should not
involve sensitive information that you would be
unwilling or unable to include in a report. For example, if the testing
environment involves secret keys, database access information, or other
information that would preclude you from including screenshoots to
demonstrate your activities (see the reporting activities below), do not
select that task or project.
-
You almost certainly should consider that another worker may
complete a selected task before you do. Some projects allow you to
"claim" issues, but almost no projects will allow you to claim all of the
issues you might select for HW6. There is no perfect solution to this; you
should consider this risk when selecting tasks.
-
You almost certainly should consider that your contribution does
not need to "actually work" or be accepted to receive full credit. Instead,
we will be grading you based on the HW6a and HW6b report evaluation
criteria. For example, "QA Evidence", which the report asks for, is
not the same as "Evidence that you totally passed all tests and
implemented everything perfectly and everyone loved you", and instead is
"Evidence that you followed a meaningful quality assurance process".
Sometimes the outcome of a process is "this patch is not good enough for
our project". It is certainly easier to present evidence if you succeeded
on all fronts, but many worried students near the end of the project have
concerns about not actually fixing the bug or having the patch accepted.
You are encouraged to double-check the grading criteria for this homework.
-
You almost certainly should consider that you may want
to carry out actions that the GitHub project itself does not strictly
require, but that can be listed in the HW6 reports. For example, if you are
worried that your report won't cover enough details to demonstrate your
mastery of the material, you might choose to communicate with a project
maintainer and ask about non-functional requirements for your patch
(e.g., "would this project prefer code that is smaller and easier to
read, but slower, like this, or instead prefer code that is more
complicated but also more efficient, like that?"). In this example, you have
created an opportunity for yourself to describe quality properties and
requirements elicitation (e.g., exploring tradeoffs) in your report. The
GitHub project may not require any such thing, but you can still choose to
do it for HW6 if you are worried about your report and your grade.
-
You almost certainly should read at least two of the example HW6b
reports made available at the bottom of this page. Many students find that
they have questions along the lines of "exactly how much evidence of XYZ
will I need for full credit, and can you promise me that if I do exactly
PQR I will get full credit?". Unfortunately, the course staff typically
cannot answer such questions directly beyond the rubrics below. However,
the example HW6b reports are a great place to get an idea for what is
expected.
-
You almost certainly should think about how big the average pull
request actually is and what the major themes of this course are regarding
reading code vs. writing code. For example, in the
Khan and Patel Zulip report,
the students report on their pull request #371 for python-zulip-api.
You can view that
pull request on GitHub and see that it only changed three lines of code
in one file. In the maintenance of legacy software, reading the project to
determine where to make a change, and in what manner the maintainers will
accept it, is often much, much harder than making the change itself (which
is often quite small).
Read this entire homework description and pick a project and task(s) that
will give you something detailed to talk about in each of the required
report sections. See the Golden Rule above. 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. Do not
pick that project, and instead pick another project.
Students often report that this homework 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
(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. If you can't contact the course staff quickly enough and are
worried about a project or task, do not select that project or task and
instead select a safer one.
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
or codetriage.com
which
list GitHub repositories with beginner-friendly labels (special thanks to
J. Kollin, P. Shultz, K. Cheng, and H.-T. Chen 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:
- 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
work.
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 thing you must turn in 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 how you make this decision. However, you should justify
that decision by grounding it in facts about the projects and tasks you
consider.
In addition, you may consider whether you want to work on a project for
Social Good. If that is of interest to you, additional resources are listed
at the of this document. You are not required to select a project
associated with Social Good, it is merely an option.
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:
- 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.
- Don't forget to tag your partner on Gradescope, not just in
the PDF document. We typically have multiple groups per semester where
partner A forgets to tag partner B, who then receives a zero on the
assignment and doesn't notice it when assignment grades are posted,
ultimately getting a lower letter grade in the class until the problem
is corrected. We don't recommend that situation.
- 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.)
- 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.
(Many students have been unpleasantly surprised in HW6b at being
unable to compile and run the program they are working on.)
- If your project has both a front-end and a back-end (or some
similar modular structure), you must show evidence of building and
running both.
- If you work with a partner, show evidence that both of you can
build and run the project.
- 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 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.)
- If the official task description is terse, you may have to read up
on relevant context. For example, suppose the official pull request
task description is just one sentence: "Remove buffer overruns from
secondary networking module."
Your report might say something like:
"The tasks is to remove buffer overruns from the secondary
networking module. In this program, the secondary networking module
does $FOO, while the primary does $BAR. The program is structured this
way for reason $BAZ. Buffer overruns are relevant because of
$SECURITY_EXPLANATION. Similar changes in the past to the secondary
module have struggled with $ISSUE. We hypothesize that the best way to
address the problem will be by adding array bounds checks or by using
$OTHER_TECHNIQUE. The project maintainer has specified that any
solution must meet $READABILITY_THRESHOLD. In addition, the task
implicitly requires that any new code meet the project's
$COVERAGE_REQUIREMENT. To obtain that, we will also create $UNIT_TESTS
..." and so on. Note that you don't need two paragraphs, the phrasing
is "up to" two paragraphs. The goal is not to convince us that you
read GitHub verbatim, but more to convince us that you understand all
of the things that will be involved in the task, even if, in shorthand,
the developers did not say all of them out loud.
- 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 (e.g., to the project maintainers); estimated effort for
each (sub)task; dependencies between tasks; and a best-effort assignment
of (sub)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
paragraph, or 1 paragraph per task.)
- Note that risks may be both personal (e.g., you are unfamiliar
with the library, you might get sick, etc.) but may also be related
to the context of the project (e.g., this GUI is hard to test, this
issue is hard to reproduce, etc.). We encourage you to take the broad
view of "risk" covered in class (and possibly review the early lectures
for some examples).
- 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.)
- In this context, the difference between a time plan and a
process plan is that the former is asking you for something like
a schedule (a calendar, a Gantt chart, etc.) and the latter is asking
you about software process. It may be worth reviewing the Lecture on
"Process, Risk and Scheduling" to see some of those terms defined.
- Very, very informally, just to highlight the difference, "We'll
use Agile" is a process description but not a time description (it
says how but not when). By contrast, "We'll be done with the testing
by December 4th" is a time description but not a process description
(it says when but not how).
- Task scope justification. Evidence that the tasks are of a
sufficient and reasonable size and complexity (for you or your team)
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.
Panic — My Project or Task Exploded
Some students end up in situations where the tasks they initially selected
do not work out (e.g., are too hard, are "sniped" by another developer despite
being claimed, etc.). Those students often wonder what bad things will
happen if they pick new tasks for HW6b, different from what they reported in HW6a.
Similarly, a few students each semester end up in very unlucky situations
where the projects they selected don't work out (e.g., the whole project
shuts down, no developer ever responds, it's not possible to build the
project locally, etc.). Those students often wonder what bad things will
happen if they have to pick an entire new project for HW6b not mentioned in
HW6a.
Nothing bad happens in such cases. You can still get full credit on
HW6b if you change tasks (or even projects). There is a place in the HW6b
report to write about such changes. Follow the Golden Rule above and
double-check what you have to turn in for the HW6b report. As long as you
can fill out all of the fields and rubric items, you are fine.
Clearly it's better and easier if you don't have to change projects or the
like. But we're not going to "charge students twice for the same crime"
and take off points just because you couldn't predict the future. Students
who have to switch things halfway through will already feel behind because
of "lost time" and will feel pressure to get up to speed on the new
project quickly. Those students usually have to spend more than the minimal
required hours on the project. That's already enough of a penalty. As a
result, there are no specific rubric items that lose you points if you
switch aspects between HW6a and HW6b.
To be clear, you should try to avoid such situations (e.g., by thinking
about risk, etc.) as far as possible. But if something does go wrong, it's
not the end of the world (or the end of your grade).
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:
- 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.
-
Selected project. A brief description of the open source system to
which you contributed (1 paragraph). You may reuse text from Part A.
- If you were very unlucky and had to change projects from HW6a, which
is entirely legal, you should mention the switch and describe the new
project in the HW6b report.
-
Social Good indication. Indicate whether or not you think the project you selected
contributes to Social Good. (Note that either answer is full credit.) If the
answer is "no", you need not elaborate. If
the answer is yes, why does the project qualify? You can use your own words, or select
from the 17 Sustainable Development Goals.
-
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.)
- (Pictures, screenshots and/or diagrams, unless excessive, do not
count for this or any other length limit for HW6.)
- (You can re-use text from HW6a if it is appropriate for any
part of the HW6b report.)
-
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.)
- If you were moderately unlucky and had to change task(s) from HW6a,
which is entirely legal, you should mention the switch and describe the
new task(s) in the HW6b report.
-
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.
- 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 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).
- (Some students perceive overlap between "QA Evidence" and "Submitted
Artifacts". That can definitely be true, but they are officially
different questions because there might
be QA activities that don't involve submitting something per se (perhaps
they involve talking to people or reading things or the like). If
something could apply to either category, it does not matter which
heading you put it under.)
- 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. Most
students report time in units of hours (e.g., "we thought we would spend
2 hours on code reading but we actually spent 8.5 hours on it").
(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
projects.
(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.
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.
- 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 (or even hours or minutes) later. We only give extra credit for
changes accepted by the HW6b deadline. (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:
- 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.
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. (Yes, you can just pick one of these
projects for your HW6.) 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.)
-
Project: WordPress-IOS
("a website builder")
- A student requested that we make this report, which is missing
sections, available as a cautionary tale of things that can go wrong.
- Final Report: Anonymous
Student
-
Project: Karrot
("web application for organization of foodsaving groups")
-
Project: Michigan ITS
Teaching and Learning Group ("tools used by students and faculty
here daily")
-
Project:
Neovim ("extensible and usable text editor")
-
Project:
Notepad++ ("source code editor")
-
Project:
OpenRCT2 ("video game that simulates amusement park management")
-
Project:
Oppia ("online educational platform")
-
Project: PeacefulCraft
Network ("a Minecraft community")
-
Project:
Thunderbird ("cross-platform email client, news client, RSS and
chat client")
-
Project: VSCode ("comprehensive editing and debugging")
-
Project: Zulip ("real-time
chat with an email threading model")
We make available the names of projects used by students from two previous
offerings of this class:
Adobe Brackets.
Ancient Beast.
Ant Design.
Arrow.
Atom.
Batavia.
beets.
Cataclysm: Dark Days Ahead.
Chronos Timetracker.
City Scrapers.
Coala.
CodeMirror.
Cosmos.
Discover Rewards Notifier.
Docusaurus.
Elasticsearch.
ERPNext.
Firefox.
GitHub Desktop.
github-for-unity.
Googletest.
Guppy.
Habitica.
Hyper.
I3 Window Manager.
Jarvis-On-Messenger.
Karrot.
LMMS.
Mission Pinball Framework.
MusicBot.
Mypy.
neovim.
Newspaper.
Notepad++.
NumPy.
Octoprint.
Open Broadcaster Software.
Open Food Network.
OpenRCT2.
Oppia.
Pandas.
Pantry-for-Good.
Peace Corp Prep Kit.
Pelican.
perfSONAR.
plots2.
Pytest.
Pytorch.
Red-DiscordBot.
Runelite.
scikit-learn.
Scrapy.
Sonic-Pi.
Strongbox.
subtitle downloader.
Sympy.
Tenor Core.
TensorFlow.
Thunderbird.
VOC.
VSCode.
wemake-python-styleguide.
wger.
Wikimedia Commons Android App.
YAPF.
Yoda.
YouTube-DL.
Zulip.