Prototype

At the start of this sprint, create a branch named prototype from main, or charter if your charter pull request (PR) has not been merged yet. This branch is your sprint’s integration branch. All work for this sprint lives here or in branches that merge into it.

Caution

Your branch must be called prototype. Not prototype-final. Not sprint-002. Not anything else.

Do not work directly on prototype. For each task or feature, create a short-lived branch off of prototype, do your work there, and open a Pull Request back into prototype when the work is ready. Name these branches descriptively (e.g., prototype/ligand-filtering, prototype/docking-wrapper, prototype/fix-smiles-parsing). This workflow gives you a clean, reviewable history of incremental changes on prototype and ensures that a broken experiment on one branch does not block your teammates on another.

When your team has met the Prototype Sprint objectives, stop adding new features. Open a Pull Request on GitHub to merge prototype into main, and explicitly request a review from your entire team and the @dri-26s account.

I will review your submission directly within the PR, adding comments on your codebase and documentation. When I request changes, you must implement them and push the updates back to the prototype branch. Re-request my review only once all requested changes are complete. We will repeat this process until the work meets production standards and is approved for merging.

Once the PR is merged into main, I will generate a formal Artifact by creating a GitHub Release. Under certain circumstances, I may directly push changes to your prototype branch if it represents the most efficient path forward. I will also step in to update other shared branches (such as dev) to assist with resolving complex merge conflicts.

Tip

Check your project specification to see what deliverables are expected to be completed in this sprint.

Commit Hygiene

Your commit history is the evidentiary backbone of this sprint. The Struggle Documentation section of your report requires permalinks to specific commits that show what you tried, when you tried it, and what changed. If your history is squashed, rebased into oblivion, or filled with meaningless messages, you will not be able to produce this evidence, and you will lose points.

Follow these rules for the remainder of the semester.

Commit early and commit often

A commit should represent a single logical change: one function added, one bug fix attempted, one parameter adjusted. Do not accumulate an afternoon of work into a single commit. If you tried something and it did not work, commit it anyway with a message that says so. That failed attempt is exactly the kind of evidence your sprint report needs.

Write specific commit messages.

Your messages must follow the Conventional Commits specification. The format is:

<type>(<scope>): <description>

Where type is one of feat, fix, docs, refactor, test, chore, or similar; scope is the module or area of the codebase affected; and description is a concise, imperative-mood summary of what changed and why.

Examples of good commit messages:

fix(docking): increase exhaustiveness from 8 to 32 to reduce pose variance
feat(filtering): add PAINS filter using RDKit FilterCatalog
docs(readme): add installation instructions for Pixi environment
fix(prepare): handle missing stereocenter in SMILES parsing (did not resolve #12)

Examples of bad commit messages:

update code
fix stuff
WIP
asdfasdf
final version?

Do not squash commits when merging Pull Requests

When you merge a PR on GitHub, select “Create a merge commit”, not “Squash and merge.” Squashing compresses your entire branch history into a single commit, which destroys the chronological record of your work. I need to see the individual steps, including the wrong turns.

Caution

If your prototype PR is squash-merged, I will ask you to revert it and re-merge with the full history intact. Protect your evidence.

Sprint Report Template

You will create a file named reports/sprint-02.md in your repository. At the end of every sprint, your team must commit a Sprint Report by 5:00 PM on Friday. Copy the following Markdown content into that file and fill in the bracketed sections. Delete these instructions before submission.

# Sprint 02: Prototype Report

**Team:** [Replace with team name]
<br>
**Date:** [Replace with date]
<br>
**Authors:** [Replace with Name(s) of Person Writing the Report]

## Scientific Status

[Briefly re-contextualize the biological problem you are solving.
Explain why this specific project matters.
State the specific gap in knowledge or tooling you aim to fill by the end of the semester.
Keep this high-level and accessible to an external scientist.]

## Sprint Outcomes

[Explicitly state whether the goals of the Prototype Sprint were met, partially met, or missed entirely.
Do not be vague.
Culminate this section in a single, decisive sentence summarizing the status of your prototype.
Remember, the goal of this sprint is to build the pipeline and run it on a toy dataset.]

### Definition of Done

[Evidence is required here in the form of links to files, data, and notes that instantly open if I click on the link.
If it is not linked, it does not exist.
Include visualizations of your prototype running on the toy dataset here.]

## Technical Struggle Documentation

This section is the most heavily weighted component of the sprint report.
You are required to document exactly two significant technical problems your team encountered and fought through during this sprint.
These must be real problems that cost your team real time.
Do not fabricate or exaggerate a struggle.
I will verify every claim against your commit history.

For each of the two problems, you must provide the following in this exact order.

### Struggle 1: [Descriptive Title]

#### What we were trying to do

[State the specific technical task you were working on when the problem surfaced.
Link to the commit or branch where this work was happening.
Example: "We were writing the ligand preparation function in `src/prepare_ligands.py` ([permalink to file at that commit])"]

#### What went wrong

[Describe the failure precisely.
Make sure to paste the exact error message, traceback, or unexpected output in a code block.
If the problem was not an error but a scientific result that did not make sense, show the data or figure that raised the flag.
Do not summarize; show the raw evidence.]

#### Why we thought our original approach would work

[Explain the reasoning that led you to the approach that failed.
What documentation did you read?
What example did you follow?
What assumption did you make?
This section demonstrates that you were thinking before you coded, not just guessing.]

#### Everything we tried, in order

[This is the core of the section.
Walk through every attempt you made to fix the problem chronologically.
Each attempt must include:]

**Attempt 1**

[Explain what you tried, and be specific.
Link to the exact commit where this attempt is visible. Use [GitHub permalinks](https://docs.github.com/en/repositories/working-with-files/using-files/getting-permanent-links-to-files) (i.e., links pinned to a specific commit SHA, not to `main` or `dev`).
If you changed a parameter, state the old value and the new value.
If you restructured code, describe what you moved and why.]

[Explain why you thought this would help. What was your hypothesis for why this change would resolve the problem?
Did you find a Stack Overflow answer, a passage in the tool's documentation, or a section of a paper that suggested this fix?
Link to it.]

[Describe what happened. Paste the new output, error, or result. Did the problem change? Get worse? Partially resolve?]

**Attempt 2**

[Repeat this numbered sequence for every attempt.
Two attempts is a minimum; I expect most real problems to involve three to six iterations.
If you solved it in one try, it was not a significant struggle.]

#### Resolution

[State what ultimately worked and link to the commit where the fix is merged.
If the problem is not yet resolved, say so explicitly.
Describe your current best hypothesis for the root cause and your plan for the next sprint.
Unresolved problems documented with rigor earn full marks.
Unresolved problems with vague documentation do not.]

#### What we learned

[One to three sentences.
What does your team now understand that you did not understand before this problem?
How will this knowledge change how you approach similar tasks in the next sprint?]

### Struggle 2: [Descriptive Title]

[Repeat the same structure as Struggle 1.]

## Planning

[Bridge this work to the next sprint.
Define the specific technical and scientific goals.
Detail exactly how you will transition from your toy dataset to production scale.
If your experiments succeeded, what is the logical next step?
If they failed, how will you pivot?]

Rubric

The sprint report is worth 25 points distributed as follows.

Section	Points	What earns full marks	What does not
Scientific Status	1	Clear, accurate re-contextualization of the biological problem. An external reader can understand what you are doing and why.	Copy-pasted from a previous report or the project specification with no evidence of the team’s own understanding.
Sprint Reporting	2	Honest, specific assessment of what was achieved. If goals were partially met or missed entirely, this is stated directly with an explanation of why. The reporting accurately reflects the state of the repository.	Vague language like “we made good progress.” Overstating what was accomplished relative to the evidence in the repository.
Sprint Completion	3	The prototype sprint objectives from your project specification are met. The “Definition of Done” section contains permalinks to working code and embedded figures showing the prototype running on a toy dataset.	Objectives are partially met with no explanation of what remains or why. Missing or broken links. No visual evidence. Objectives are unmet.
Struggle 1	8	All six subsections are present and substantive. Every claim is backed by a permalink to the relevant commit. The “Everything we tried” section contains at least three chronological attempts, each with a hypothesis, an action, and a result. The reasoning is genuine and specific to your problem, not generic.	Fewer than three attempts documented. Missing permalinks. Descriptions that read like a tutorial rather than a narrative of real debugging. Evidence that the “struggle” was trivially solvable (e.g., we didn’t know how to use a tool so we had to read the documentation).
Struggle 2	8	Same criteria as Struggle 1. The two struggles must be meaningfully different problems, not two symptoms of the same root cause.	Same root cause as Struggle 1 repackaged. Substantially less detail than Struggle 1.
Planning	2	Specific, actionable goals for the next sprint that clearly follow from the current sprint’s results and struggles. Identifies at least one risk or open question.	Generic to-do list with no connection to what was learned this sprint.
Writing quality	1	Professional, concise scientific English. Markdown is well-formatted. The report could be handed to the project sponsor without embarrassment.	Sloppy formatting, grammatical errors that impede comprehension, or an unprofessional tone.

What does “struggle” mean?

I am not grading the difficulty of the problem. I am not grading whether you solved it. I am grading the depth and honesty of your engagement with the problem.

A team that documents a week-long fight with a subtle data parsing bug (e.g., showing every wrong turn, every hypothesis, every dead end) and ultimately does not solve it will earn more points than a team that presents a neatly resolved problem with no evidence of the messy middle.

The reason is simple. In research, and in your careers, you will spend most of your time stuck. The skill that separates productive scientists and engineers from unproductive ones is not the ability to avoid getting stuck. It is the ability to systematically work through being stuck: to form hypotheses about what is wrong, to test those hypotheses, to document what you learn, and to use that knowledge to make the next attempt smarter than the last.

That is what this course is designed to practice and reward.

Pull Request

Use the Pull Request ‘Body’ as your cover letter to summarize what to review. It helps the reviewer orient themselves before they dive into the code. Always fill out this section.

Last updated on March 8, 2026