This course culminates in a group project. Your project is a serious engineering undertaking, where you will identify a problem (in a very broad sense) and attempt to build software that solves the problem (in a broad sense).

The key constraint here is that you must use a pure functional language, like Haskell, Elm, PureScript, or Coq. (There are others, but I particularly recommend the first three of these.)

Deliverables

Date Deliverable
Tuesday, March 10th preliminary project proposals due in class (bring a printout)
Friday, March 13th project proposals due at 10pm
Biweekly, after spring break check in with me about how things are going
Thursday, April 16th Thursday, April 23rd progress report due in class (bring a printout)
Thursday, April 30th Friday, May 8th final writeup due in class (bring a printout)

Your project is not just code! Along the way, you will need to build significant infrastructure, write documentation in a variety of forms, present your work, and review your peers.

Proposal

Your final project proposals are due Friday, March 13th at 10pm. I expect you to submit a draft proposal before class on Tuesday, March 10th. Bring a single printout.

Your proposal should not exceed two pages. It should contain the following headings:

  • Project Name: Your project’s name. (You can change it later, but a mnemonic helps.)
  • Team: All of the group members’ names and GitHub account names. (If you don’t have a GitHub account, please create one now.)
  • Description: A short, single-paragraph summary of your project and its goals. What need are you addressing, and for whom?
  • Plan: A description of your planned design. Can you break your project into modules or other subparts? Who will work on which parts? Which libraries will you use? How will you test? What are the hard parts?
  • Timeline: A timeline. What order will you build things in? What will you have ready, when? I expect your team to meet at least once a week outside of class. When will it happen?
  • Success criteria: Your success criteria. A paragraph or two should delineate not only your ideal goals, but also one or two “fallback” positions you can take if your project turns out to be too ambitious.

Your proposal is, in a certain sense, a contract. It’s a set of goals and a plan to achieve them—and we should all agree that your goals are reasonable and your plan is workable.

Code

Your code will live on GitHub in this semester’s organization.1 Your repository will be public. If you don’t have a GitHub account, please create one now. Once you have submitted your proposal, I will create the appropriate teams in the organization and add you to the repository.

You will write ‘good’ commit messages that describe what changes you’ve actually made. For example, saying “fixed it!” is a lovely thing to do, but it will be clearer if you say what you fixed and how.

If you’re pair programming or otherwise working as a group, it’s helpful to mention everyone who worked on a given commit. You can do this explicitly using co-authors. (You don’t need to set co-authors, but it’s a good idea if you’d like to know who wrote which lines of code—which tells you who to talk to when you’re debugging!)

I strongly recommend that you use Stack to manage your project and its dependencies. Depending on what you’re building, Stack may offer useful templates for you to start.

Your code will be “finalized” when you hand in your final writeup. I would love it if you continued to work on this project, but I’ll be grading the version of the project that exists at 9:35am on April 30th (or May 5th, if we go with a single day of presentations).

Infrastructure and testing

You will implement tests. I don’t particularly care which framework for testing you use, but it’s important that:

  1. You continue to write tests as you write code!
  2. As much as possible of your testing should be automatically runnable via a single command.

Testing UI projects is hard, and while you can test webpages and web apps, you’ll have to balance your testing effort with the actual reward. Depending on what kind of project you’re working on, you might want to include benchmarks in your tests.

You will use continuous integration (CI) to ensure that your code works. CI is a process that ensures that your software is continuously tested, i.e., your code will be built and tested at fixed events (e.g., a commit to the GitHub repository) and intervals (e.g., once a day). Unless you have a particular reason to use a different service, you should use Travis CI.

Bug journal

In addition to writing good commits, I expect you to keep a bug journal. This can be a file in the repository, a shared document—the organizational method you use doesn’t matter so long as you can submit it to me.

The goal of the bug journal is to document the issues you run into. These will vary widely, from “can’t get a library to install” to “my code has the wrong behavior” to “things are behaving differently on different devices” to “I’m not sure how to implement this feature with the tools I have”.

Each entry in your bug journal should have the following format:

# BUG 2020-03-05 #1

Problem: I'm having trouble getting foo to bar the baz.

Who: Prof. Greenberg, Opie the dog

2020-03-05 Not sure why foo isn't barring things. The call is right there!

2020-03-06 The baz isn't loading in CI at all. Maybe that's why it isn't getting barred?

2020-03-07 Opie fixed it! Upgraded to baz-0.6.3, fixed the initialization routine. Good boy.

That is, you’ll number each bug/problem/issue sequentially, updating the record whenever you work on the problem. It’s probably easiest to create a file BUG.md2 and store it in your repository.

Checking in

I expect your team to meet at least once a week outside of class. It will probably be most productive for you if you can find several times at which most or all of you can get together to work on the project.

Additionally, I expect you to meet with me at least once every two weeks. It’s up to you to schedule this: it can happen after class, in office hours, or by appointment.

Progress report and final writeup

In addition to your initial proposal, you’ll provide two writeups: a progress report and a final writeup.

The project checkpoint is Thursday, April 16th Thursday, April 23rd; your progress report is due at the beginning of class. Bring a single printout. Your progress report should be no more than two pages, summarizing what you’ve done so far and what’s left to do. You might need to rescope your project’s goals at that point—to do so, your group and I will need to come to an agreement.

Your final writeup, due the day of presentations on Friday, May 8th, will have a similar format: no more than two pages, summarizing the projects initial goals, describing what’s been achieved, and what’s left to do. Your final writeups will be peer reviewed, which means your classmates need to know what you’re talking about. Clarity is vital!

Presentation

I’ve reserved Thursday April 30th and Tuesday May 5th for presentations. We’ll have a virtual meeting as a class some time after Friday, May 8th at a mutually agreeable time. If we can’t find such a time, I’ll ask those students who can’t make the best-for-the-majority time to pre-record a video.

Your group will present on your project, using slides to describe what you’ve done. What were you goals? What was hard? What was easy? What didn’t you expect? Your presentation should in some sense mirror what’s in your writeup, but you don’t need to present the same information.

Peer review

You will write two sets of peer reviews:

  • One for each of your groupmates, based on working with them over the course of the project. How were they as collaborators? What did they do really well? When did they save day? What do you wish they did better?

  • One for each of the other groups, based on their presentation and writeup. What was clear in their presentation and writeup? Did they do anything particularly cool or clever? What did they do really well? Do you think they achieved their goals? What do you think they could do better?

The reviews will be a maximum of one page per groupmate and one page per other group.

I expect both candor and kindness in your reviews. No one but me will read your reviews, but I may use them to summarize feedback to each group.

Grading

Your project grade will be calculated as follows:

It is hopefully clear that you can get a good grade on your project without meeting any of the project’s goals. The key is to continue to make progress, contribute well to the group, and have good explanations in your written deliverables (the bug journal, writeup, and presentation).

  1. When the course is over, you can fork the repository to your own GitHub profile if you want it to be part of your “open source CV”.↩︎

  2. The .md suffix indicates Markdown, a plain-text format that has become a standard way to indicate formatting on the Web.↩︎