Project: WebNorn Mailing List System (Phase 2)
- Team contract due
- Wed May 3, 10pm
- Milestone due
- Tue May 9, 10pm
- Specs due
- Fri May 12, 10pm
- Project deadline
- Wed May 17, 11am
- Reflection deadline
- Wed May 17, 11am
This is phase 2 of the Norn mailing list system. Recall that in phase 1 you built a console-based system that could evaluate mailing list expressions and display the resulting set of recipients.
In phase 2, you will add the ability to redefine mailing lists, load and save list definitions from a file, and provide a web user interface so that the system can be used from a web browser.
The purpose of phase 2 is to help you gain more experience with:
- Working with client-server networking, particularly in a web server
- Working with threads and concurrency in a substantial program
- Understanding and reusing code that other people have written (i.e., what makes code easy to understand?)
- Adding new features and adapting to changed requirements (i.e., what makes code ready for change?)
- Working in a small group with software engineering techniques like version control, specifications, and unit testing
Design Freedom
On this project, you have complete design freedom to choose the packages, interfaces, classes, and method signatures you use in your code.
Choose them wisely; your design decisions will be part of your grade.
You will be expected to use specs, tests, abstraction functions, rep invariants, safety arguments, checkRep and other assertions, and thread safety arguments.
The specification in this handout constrains what your solution must do, but you will have many design questions that are not answered in this handout. You are free to come up with your own answers to these questions – just be reasonable, consistent, safe from bugs, easy to understand, and ready for change. You can always ask your TA mentor or on Piazza for advice, but there is unlikely to be a single hard-and-fast answer.
On this project, Didit will run only your own tests. As always, correctness is your responsibility, and you must rely on your own careful specification, testing, and implementation to achieve it.
Your team’s repository
To get started, (note: only available after the project announcement in class)
- One member of your team should ask Didit to create a remote
projects/norn2repository, which will create a single repository shared by all members of your team. Then all team members will be able to clone the repo from Athena using Git:
git clone ssh://username@athena.dialup.mit.edu/mit/6.031/git/sp17/projects/norn2/username1-username2-username3.git norn2
List usernames in alphabetical order.
Overview
During the project, class meetings will be partly or completely replaced by team work time. Your team is expected to meet and work together during these times.
Checking in
Your team will be assigned a TA mentor who will help you with your design and help you stay on track as you implement it. You are required to check in with your TA during every team work time class. At this check-in, each team member should describe:
- what they have accomplished since the last check-in
- what they plan to accomplish by the next check-in
- what, if anything, is blocking their progress
Use the check-in to review how each person’s plans fit together and decide how to resolve blocking problems.
Working together
Other than reflections at the end of the project, all parts of the project should be committed to the repository you share. Each commit to the repository should have a useful commit message that describes what you changed.
Use the code review skills you’ve practiced on Caesar to review one another’s code during the project. Caesar won’t have your project code loaded into it, however, so you can use in-person discussion or email for these reviews.
You are also strongly encouraged to try pair programming, where two people collaborate on a single computer. Pair programming is a skill that requires practice. Be patient: expect that pairing will mean you write code more slowly, because it’s like code review in real time, but the results are more correct, more clear, and more changeable. You can find plenty of advice on the Internet for how to structure your pairing.
When multiple people contribute to a commit, mention them in the commit message. Your TA will be reviewing the Git log to see individual contributions.
Pull before you start working, commit and push frequently, and don’t break the build!
Tasks
Team contract. Before you begin, write and agree to a team contract.
Understand the problem. Read the project specification carefully.
Design. You will need to write a grammar for parsing list expressions; design an immutable recursive abstract datatype (an AST) for those expressions; design an abstract data type for storing list expressions that have been given mailing list names; design a frontend that interacts with the user at the console; and other components.
Your software design is perhaps the most important part of the project: a good design will make it simpler to implement and debug your system. Remember to write clear specifications for classes and methods; write data type definitions for your expression data types; define abstraction functions and rep invariants, and write
toStringandcheckRep; and document safety from rep exposure.Test. You should write JUnit tests for the individual components of your system. Your test cases should be developed in a principled way, partitioning the spaces of inputs and outputs, and your testing strategy should be documented as we’ve been doing all along.
Implement. Write implementation code so that your tests pass. Iterate on the design and tests as needed to make the system work.
Reflection. Individually, you will write a brief commentary saying what you learned from this project experience, answering the reflection questions. Your reflection may not exceed 300 words.
Dividing the work
Every team member must not only make a substantial contribution to the project, but every team member must make a concrete contribution to every major component of the project.
For example, you may not assign one team member who is solely responsible for the parser.
Contributions include writing specifications, writing testing strategy, writing tests, prototyping, writing internal docs, writing implementation code, fixing bugs, and giving code review feedback. Contributions you work on as a pair or a whole team are great, as long as everyone is involved. Tasks like running meetings, taking notes, and tracking bugs are important, but don’t count as contributions under this requirement.
You must also divide the work such that every team member makes several different kinds of contributions.
For example, you may not assign one team member who is solely responsible for writing tests.
Here is one suggestion for how to break down the work for a 3-person group. Fill in the cells of this grid so that it is a Latin square, i.e. no person is mentioned more than once in each row or column:
Core ADTs | Console UI | Web UI | |
|---|---|---|---|
Specs | |||
Tests | |||
Code |
Automated testing
Didit will compile your project and run your tests every time you push.
The automated testing page describes how Didit finds your tests, what tests can and cannot do, and how to exclude tests from execution.
You are not required to run any of your tests on Didit, but your project must compile and have a green build on Didit in order to be graded. If it doesn’t build on Didit, your TA won’t be able to build it either.
Specification
The project specification describes how the mailing list system must work for this phase of the project.
Provided code
Your starting repository has a Main class with an empty main method.
You may also find earlier staff-provided code to have useful models, or even starting points, for your design and implementation:
Reuse and Integration of Phase 1
You are now in a new group for phase 2, and each of your group members has a different phase 1 implementation of the project. So your first step is to review each other’s phase 1 projects, discuss the pros and cons of their design and coding, and decide how to integrate them.
Each member of your group must bring at least one significant contribution from phase 1 into the integrated implementation. You don’t need to have been the primary author of what you are bringing from phase 1, but you must certainly understand it, be able to explain it to your teammates, and be able to integrate it with their contributions. Examples of significant contributions include:
- grammar;
- expression AST;
- ADTs representing an email address or a set of list definitions;
- console UI;
- a substantial test suite for some part of the project
You may also choose to reimplement some or all of the phase 1 project from scratch. If you choose to reimplement it entirely, then each group member still has to bring a significant contribution from phase 1 in the form of design – e.g., a set of ADT operations, or a testing strategy.
You will have a meeting with your TA early in the project (see the timeline below). At this meeting, you will have to demonstrate that you have regained the phase 1 milestone in your new group – i.e., that your new group’s implementation satisfies the phase 1 requirements for evaluating list expressions at the console. Each of you will also explain what significant contribution you brought from phase 1.
Deliverables and grading
- Wed May 3, 10pm
- Your team contract must be committed to your group repository in a PDF file called
team-contract.pdfin the top level of your repo. - Wed May 10, 11am
- Milestone meeting: you will have a meeting with your group’s TA mentor, at which you will need to demonstrate: (a) a complete version of the phase 1 project, working and committed to your repo, with each group member able to articulate what they brought from phase 1; and (b) some progress on specifications for phase 2 classes and methods, including a concurrency design (thread safety arguments for your console UI and web UI). Commit code and specifications to your group’s repository by Tue May 9, 10pm. You will demo the code and discuss your work at the meeting. Have a laptop with the program ready to run.
- Fri May 12, 10pm
- You should have committed (1) specs for all your phase 2 classes and methods, and (2) some progress on testing and implementation.
- Wed May 17, 11am
- Project deadline. Your specifications, tests, and implementation should be complete and committed to your group’s repository.
- Wed May 17, 11am
- Reflection deadline. Individually, you should write a brief reflection and submit it using the reflection form. Your reflection should be at most 300 words of plain text.
Grades will be determined according to the following breakdown:
- Team contract: 5%
- Design: 25%
- Implementation: 40%
- Testing: 25%
- Reflection: 5%
The warmup and specifications deadlines are graded as binary checkoffs. Missing each of these intermediate deadlines will cost 5 points on the overall project grade. The associated milestone meetings also contribute to your design and implementation grades.
Check-ins with your TA mentor are also graded as binary checkoffs, either passed or missed. Missing a check-in costs 1 point on the overall project grade. You should check in with your mentor during class on:
- Wed May 3
- Wed May 10 (this is the milestone meeting)
- Fri May 12
- Mon May 15