Group Project

You will work in a team of 3 to 4 to change a real open-source project. Each of you takes one request, designs a change that answers it, and implements it. The team combines everyone's changes into one working version.

You design and build as a team, but you are graded individually. Every graded part of this project belongs to one student: your section of the RFC, your change, your evidence, your part of the slides, and your answers. Your section of the RFC says how your change fits with your teammates'.

A working feature is only part of this project. You also have to show that your change improved the design of the code, and that you did not break anything.

What	When
Teams formed	Monday, September 21
G1: RFC draft	Sunday, September 27, 11:59 pm
Design critique, in class	Monday, September 28
G2: implementation, final RFC, and slides	Sunday, October 4, 11:59 pm
Presentations, in class	Monday, October 5 and Wednesday, October 7

Late days cannot be used on this project. A late G1 or G2 scores zero.

Repositories and Requests¶

We provide three repositories. Each is a copy of an open-source project in the course GitHub organization, fixed at one commit.

Course copy	What it is	Your TA
Excalidraw	A whiteboard for hand-drawn diagrams that runs in the browser.	Sanjay Kumar Baskaran
Audiobookshelf	A self-hosted server for audiobooks and podcasts, with a web client.	Soham Narendra Joshi
opencode	An AI coding agent that runs in the terminal.	Riya Elizabeth John

We assign each team to one of the three projects at random, three teams to a project. You claim requests only after that.

Each team works in its own fork of the course copy, not of the upstream project. One teammate forks it, keeps the fork public, and adds the others as collaborators. Large histories can be slow to clone. git clone --depth 1 of your fork is fine.

Each request describes something a user wants, in four parts:

Request. What the user wants.
Baseline and starting point. How the project behaves today, and where to start reading.
Minimum and checks. The smallest result that answers the request, and the checks we will look at.
Design question. A design decision that you have to make.

The requests are issues in your project's course copy. Each team member takes a different request. No two students can take the same request, even on different teams.

To reserve a request, comment on its issue. The earliest claim wins. If someone has already commented, pick another issue. Wait for your TA to confirm before you start. We confirm by editing the issue body and adding a comment. GitHub will not show you as assigned. Do not claim more than one issue.

The TA checks that the requests in a team are comparable in scope, and may ask a team to swap one. Reserve a request as soon as possible. You cannot start your design or your section of the RFC without one.

Your TA is your contact for questions about the repository and the requests.

What a good change looks like¶

You could answer a request by adding new code beside the existing code and leaving the design as you found it. Instead, change the existing design so that the request fits, and so that the next request like it costs less.

A change that only adds beside the existing code does not meet the goal of this project, even when the feature works. Most requests include a check that two parts of the app agree, for example a preview and the result that gets saved. If you copy existing logic into a new place instead of reusing it, the two can disagree, and the check catches that.

For your request, say what behavior must stay the same and how you will check that it did.

G1: RFC Draft (due Sunday, September 27)¶

Write an RFC in a shared Google Doc, using the template. The link makes a copy in your Google Drive. You need to sign in with your CMU account for access. One teammate makes the copy and shares it with the others.

Complete the shared sections as a team.
Each student writes the section for their own request.
Write the RFC yourselves, without AI.
Write in the shared document so that its edit history records who wrote what. Staff read that history.

Add both course instructors and your assigned TA as editors of the document. Their addresses are on the course home page. Set sharing so that anyone at CMU with the link can comment. The other teams on your repository review your RFC on Monday. Every student submits the link to the Gradescope assignment "G1". Teammates submit the same link, each from their own account. Name the submitted version "G1 submission" in the document's version history before you revise it further.

G1 is a checkpoint. We check only that it is a reasonable attempt. Your RFC is graded in its final form, with G2.

A reasonable attempt means that every heading in your own section except Response to Review, and every shared heading, is answered for your request and this codebase:

it names the files and functions your change involves,
it proposes a design specific enough that another team can disagree with it,
it says what must stay the same and how you will check it.

A section of placeholders, one-line answers, or text that would fit any request in any repository is not a reasonable attempt. Other teams review your draft on Monday. A superficial draft gets superficial feedback.

Your RFC is graded only if your G1 draft was a reasonable attempt, submitted on time. If your section is missing, late, or not a reasonable attempt, you forfeit the RFC part of your grade, which is 40% of the project. A teammate's missing section does not affect your RFC grade.

Design Critique (Monday, September 28, in class)¶

You review the RFCs of the other teams on your repository, and they review yours. This is your feedback before the RFC is graded. Staff give feedback in the session too.

Afterward, revise your RFC. Fill in the Response to Review section of your RFC: the feedback you acted on, and the suggestions you chose not to follow, with your reasons.

G2: Implementation, Final RFC, and Slides (due Sunday, October 4)¶

Implement your change and combine the team's changes into one working version. Check the result against your RFC. Record the evidence: the checks you ran. Where your design changed, or where work is unfinished, say so and say what follows from it.

AI may help with implementation, under the course AI policy. You must understand your change well enough to explain and defend it.

Your code and your README live in your team's fork. Everything else (including transcripts) goes to Gradescope, as files or links.

In your fork:

The combined version, at the commit you want graded. The commit must have been pushed before the deadline. GitHub records when each push arrived.
A short README that says how to run the combined version and how to check it. For each student it gives the change, the results of the checks, what changed from the RFC, and what remains. Your fork is public, so you may identify yourselves by GitHub username.

Every student submits their own zip to the Gradescope assignment "G2".

submission.txt    your request, the fork's URL, the exact commit to grade, and the link to your revised RFC
transcripts/      your own AI sessions

submission.txt: teammates will usually give the same links and the same commit. If the combined version does not show your change working, also give a commit where your change works on its own, and say what went wrong in combining. You are not penalized for a teammate's unfinished or broken work.
Slides: one Google Slides deck per team, which we created and shared with you. You should have received an invitation to your team's deck at your CMU account. If you have not, tell us as soon as possible. Work in that deck (and not a copy of it), since it is the one we will project for your presentation and grade. What goes on the slides is under Presentations below. You are graded on your own slides, not your teammates'.
Nothing changes after the deadline. We grade your RFC as it stood at 11:59 pm on October 4, and your slides are final at the same deadline. Name that version "G2 submission" in each document's version history. If you forget, we use the last version from before the deadline.
Transcripts: your own complete AI sessions. Do not put transcripts in your fork. The fork is public, and transcripts can contain file paths, credentials, and anything else you pasted into a session. See the transcript instructions.

Write the README, the slides, and every explanation of your decisions and results yourselves, without AI. Keep them short, and link to code and test results where that helps.

Presentations (Monday, October 5, and Wednesday, October 7)¶

Each student explains their own change and answers questions from staff and classmates about the design and the implementation. No demos and no elaborate slides are required. We will project your team's deck on our laptop.

The deck has one team slide and two slides per student: one you show, and one we read (hidden when you present). Do not add more. The team slide names the team, the repository, and the speakers in order. Do not introduce the project. You can assume the audience is familiar with the basics of the project.

The slide you show is a visual aid for your change: a diagram (best), screenshots, or a small diff. It has to help describe your actual design, so the room can see what you worked on and what you changed. Keep it high-level, and do not go deep into implementation details. How you set up this slide is otherwise up to you. Plan to speak for approximately 30 seconds on each of the following:

What does the user get? The feature (ideally shown).
What in the existing code got in the way, and what did you change?
One decision you made, and what it makes cheaper or harder later.

The slide we read is the template in your deck. Fill it in:

I changed: the existing part you changed (your refactor).
I added: the new part (your new feature).
I chose: the design decision that mattered most to your change.
Instead of: an alternative you considered.
Because: what the choice makes cheaper or harder later.

It is marked as skipped, so it does not appear when you present. We read it before the session and will use it for grading.

Each team has 15 minutes. Each student has three to five minutes, including questions, depending on the size of the team. Expect at least one question yourself, about your slides or your section of the RFC.

Five teams present on Monday and four on Wednesday. We will spin a wheel in class to pick who presents next. Any team can be called on Monday, so every team comes prepared on Monday.

When you are not presenting, you fill in a paper feedback sheet and hand it in at the end of class. Attend both sessions, even if you already presented on Monday. Attendance counts toward participation, separately from the project grade.

AI Use¶

Work	AI allowed?
Reading and navigating the repository	Yes
Writing the RFC, including your Response to Review	No
Reviewing other teams' RFCs	No
Implementation and tests	Yes
README, slides, and explanations of your decisions and results	No

Grading¶

The project is 20% of your course grade.

Part	Weight	Graded on
Your RFC (final version, submitted with G2)	40%	Your reasoning about the design and its alternatives. Checks that behavior is preserved. A plan you could carry out. How your change fits with your teammates'. Your response to the critique.
Your change and your evidence (G2)	45%	Evidence from checking your change. Your explanation of decisions, results, and limits in the README. How your change fits with your teammates', in the combined version where one exists.
Your presentation	15%	Your slides. Your understanding of the project, shown when you answer questions.
Transcripts	required	Ungraded, but your submission is incomplete without yours.

The RFC part is graded only if your G1 draft was a reasonable attempt, submitted on time (see G1 above).