CPSC 329 Project P1 — Hedgehogs Variants

In this (mostly) group project, you and a partner will extend the Hedgehogs in a Hurry game from project P0. This project has two parts:

• Part A focuses on teamwork: working with existing code, code review, team version control, and planning and splitting work.
• Part B focuses on designing flexible, reusable code.

Contents

• Logistics and Due Dates
• Part A
  • Functionality Specification
  • Tasks: A0: Setup | A1: Seeded Dice | A2: Code Review | A3: Choosing a Codebase and Responding to the Code Review | A4: Scripted Dice
• Part B
  • Functionality Specification: Dice Roll Modes | Black Square Variants | Turn Variants | Choosing Variants
  • Tasks: B0: Preliminaries | B1: Design | B2: Plan and Implement | B3: Wrapup
• Requirements: Program | Code | Process
• Team Process
  • Team Kickoff | Meetings and Team Log | Communication and Shared Records
  • Planning and Splitting Work | Effort Estimation | Ownership | Cooperative Programming
  • Version Control | Pull Request Reviews | Test Early
• Deliverables and Handin
• Assessment

Logistics and Due Dates

• Teams. You'll work in pairs, starting from both partners' P0 codebases. If your P0 isn't complete enough for your partner to work with, a reference implementation is available as a substitute (see A0). The teams will be the same pairs that have formed in lab: Jubayer and Andrae, William and Anik, Sebastian and Henry, Ainsley and Brooke.

• Individual and team work.

  • Task A1 (seeded dice) is individual. The code and associated deliverables must be entirely your own work, though you may ask your partner questions about their code. No pair programming on A1!

  • Task A2 (code review) is also individual. Do this on your own, without help from your partner.

  • The rest of Part A and all of Part B except the B3 wrapup are team tasks, though many of the deliverables are individual. The individual deliverables must be entirely your own work, while the code and team deliverables must be entirely your team's work.

• No AI. Review the course AI policy for details.

• Check-in meetings. Two short check-in meetings are required:

  • After completing Part A. It's strongly recommended that this be done by Wednesday 10/7 so that you have enough time to finish Part B.
  • After the Part B design (B1), before planning and implementing. It's strongly recommended that this be done by Thursday 10/15 as there is less than a week after fall break.

  Drop in during office hours — no appointment is necessary unless you are unable to make any of the scheduled office hours.

  The check-in meetings aren't graded; their purpose is to make sure your team is on track. At least one partner must attend each meeting and both are encouraged to attend. In addition, each partner must attend at least one of the two meetings, so if only one of you comes to the first check-in, the other must attend the second.

• Hand-in meeting. A 20-minute individual hand-in meeting is required after handin of the whole project. These meetings will be scheduled before the due date and normally take place within a day or two of it. Be ready to walk through your own code and other deliverables. Also be ready to explain parts of your partner's work, and bigger-picture things like design decisions and your team's process. This isn't a quiz about content; it's to confirm that your handin reflects your own understanding and effort.

• Due Monday 10/26 at the start of class. There is a single handin for both parts. Late handins are not accepted for projects, but an occasional 1-2 day extension is possible in case of a last-minute time crunch. (Plan ahead to avoid this!) See the late policy for details.

Part A

In Part A, you'll add reproducible dice rolls to the game, which is handy for testing. Read through this whole part (sections marked with "[A]" in the heading) to get an overview of what you'll be doing, then work through the five tasks in the Tasks section in order.

[A] Functionality Specification

Reproducible Dice Rolls

It can be useful for testing to be able to replay the same sequence of turns. Since the rest of the game is deterministic, this only requires being able to repeat the same sequence of dice rolls: with the same rolls and the same player input, the game plays out the same way.

Computers typically do not generate truly random numbers; instead a pseudorandom number generator produces a sequence of numbers that appears random but is completely determined by a starting value called the seed. Two generators created with the same seed produce the same sequence of numbers. In Java, new Random(seed) creates a generator with the specified seed.

While the same seed ensures the same sequence of values, ensuring the same sequence of dice rolls requires a few additional things:

• All dice rolls come from a single generator. The generator is created once, with the game's seed, and every roll is drawn from it.

• The dice generator is used only for dice rolls. Nothing else draws numbers from it.

• Exactly one roll occurs per turn. The die is rolled once, at the start of each turn, regardless of what happens during the turn, including turns in which the forward move turns out to be impossible or where invalid input results in a reprompt.

If these conditions hold, a game can be replayed exactly by starting it with the same number of players, the same dice choice, and the same sequence of player moves.

Three dice roll options should be supported:

• Random — the standard option, where a new sequence of dice rolls is used for each game. Print the seed needed to replay the game at the beginning and the end of the game.

• Chosen seed — prompt for the desired seed on game startup. Any value that fits in a Java long (including negative values) is a valid seed. Print the seed at the beginning and the end of the game.

• Dice script — prompt for a filename on game startup. Dice rolls are taken from the file, one per turn. If the script runs out of rolls before anyone has won, continue with a random seed and print a message to that effect.

There's no way to find out a Random object's seed once it has been constructed, so for random mode it is necessary to generate a seed first and then create the dice generator with that seed. An option here is to create a Random object with the default constructor and use that to generate a random value for the seed. Create a new Random object with the seed to use for dice rolls. Usability suggestion: seeds that are at most 7-8 digits long are much easier to read and type, so consider limiting the range of generated seeds.

[A] Tasks

Do these tasks in order.

A0: Setup

This project starts with each partner working with the other's codebase before settling on one to continue with for the rest of the project.

A1: Seeded Dice

This is an individual task — no pair programming! You may ask your partner questions about their code if there is something confusing, but not otherwise work together on this part.

Add the random and chosen seed options to your partner's P0 codebase (not your own!). To do this:

Note that all A1 deliverables (other than the initial change impact report submitted on Canvas) go into your partner's repository.

A2: Code Review

This is an individual task.

A3: Choosing a Codebase and Responding to the Code Review

This is a team task.

The rest of these steps should be taken in the chosen codebase. Note: don't delete the other repository even though it won't be extended further! It is an essential record of work from project P0 and tasks A1-A2.

Plan and split the work identified in the code review (see Planning and Splitting Work in the Team Process section):

Now do the work:

A4: Scripted Dice

This is a team task.

Add the dice script option to the chosen codebase. To do this:

Part B

In Part B, you'll add several rule variants to the hedgehogs game. Read through this whole part (sections marked with "[B]" in the heading) to get an overview of what you'll be doing, then work through the four tasks in the Tasks section in order.

[B] Functionality Specification

Dice Roll Modes

In addition to the random, chosen seed, and dice script modes from Part A, the program should support fixed dice — a die that always rolls the same specified value. Fixed dice are for testing, not game play, so they are not offered as an option at the start of the game.

Black Square Variants

Each variant changes how black squares behave; all other rules are unchanged, and the black squares remain in the standard positions. Unless stated otherwise, a variant's effect applies whenever a hedgehog enters a black square, whether by a forward move or a sidestep.

• Urhedgehog — Black squares function as ordinary squares. Hedgehogs on them are never blocked.

• Super Turbo Hedgehogs — Black squares are trampolines. A hedgehog that enters a black square immediately moves one more square forward in the same track, landing on top of any stack there. (If that square is the goal column, the hedgehog has reached the goal.)

• Concrete Block — Hedgehogs cannot enter black squares at all. A forward move or sidestep that would put a hedgehog on a black square is illegal. If no free hedgehog in the rolled track can legally move forward, the forward move is skipped, as usual.

• Slide — A hedgehog that enters a black square slides back to the start column in the same track, landing on top of any stack there.

• Pits — A black square traps only the first hedgehog to enter it. A hedgehog entering an empty black square cannot leave until all columns behind it are empty, as in the standard game. Hedgehogs entering a black square that is already occupied stack on top as usual, and the top hedgehog is free to move forward as with a normal square.

• The Black Hole — A hedgehog that enters a black square is permanently removed from the game and the first player to get one hedgehog into the goal column wins. Players with no remaining hedgehogs continue to take turns, including rolling and making any required forward move with an opponent's hedgehog. If at any point only one player has hedgehogs remaining on the board, that player wins.

Turn Variants

Each variant modifies a single step of the turn. A turn still consists of a roll, an optional sidestep, and a forward move, in that order.

• Fizzy Lifting Hedgehogs — If the current player has no legal sidestep available, they may instead choose a stack containing at least one of their own hedgehogs and move (lift) their lowest hedgehog in that stack to the top. Lifting is optional and takes the place of the sidestep for that turn.

• Anarchohedgehog — Any free hedgehog may be sidestepped, not only one of the player's own.

• Hedgehogs Pushing — If the normal forward move is impossible, instead move every free hedgehog on the board forward one square in its own track, except for hedgehogs in the column immediately before the goal column. The push is simultaneous: the set of hedgehogs that move is determined before any hedgehog moves, and a hedgehog arriving on a square is placed on top of whatever remains there after the push. Each pushed hedgehog is subject to the black square rules in effect, and a hedgehog that cannot legally move forward remains in place.

Choosing Variants

At the start of the game, after choosing the dice mode, the players choose a black square variant and a turn variant. The standard rules are the default for each. Any combination of dice mode, black square variant, and turn variant must work.

[B] Tasks

Do these tasks in order, continuing with the codebase chosen in Part A.

B0: Preliminaries

This is a team task.

B1: Design

This is a team task, starting with an individual step.

Part B involves three variation points where the behavior can vary among several alternatives: dice roll modes, black square variants, and turn variants. Your design must support all of the dice roll modes and rule variants in the functionality specification, even though you'll implement only a few of them — the point is a design that makes adding the other variations straightforward. (Implementing additional variants beyond those required is extra credit.)

B2: Plan and Implement

This is a team task.

B3: Wrapup

This is an individual task.

Points to address in the reflection:

• Design. For the rule variant refactoring (black squares or turns) that your partner owned, address:

  • Patterns. If design pattern(s) were used, name them and explain why they fit; if no pattern was used, explain why. Then describe a reasonable alternative design — either another pattern or no pattern at all — and compare the approaches. Which is better and why?

  • Adding a variant. Walk through what would be required to add one of the variants that wasn't implemented: which classes you would add, what existing code (if any) would have to change, and why. Where does the design make this easy, and where does it fall short? What would you change if you were to redo it? (If your team implemented all of the variants, pick one that your partner implemented.)

  For the rest of the codebase (outside the variation points):

  • Principles. Give two examples of code that follows or violates a design principle discussed in class. For each, name the principle, point to the specific class or method, and explain how the code follows the principle or violates it.

• Planning and estimation. How did your estimates compare to the actual sizes over A3, A4, and Part B? Did your estimates get more accurate? Did comparing independent estimates surface misunderstandings that would otherwise have caused problems later?

• Process and teamwork. Was sketching designs individually before designing together useful? What worked well in how your team worked together, and what would you do differently next time?

Be honest and thoughtful — whether you found something useful or not won't affect your grade. What matters is what the experience taught you about software development.

Requirements

These are the end results your work (Parts A and B) is assessed against (see Assessment). Team code is assessed according to ownership.

Program Requirements

For the chosen codebase:

• Reproducible dice rolls. The random, chosen seed, and dice script modes are supported as specified and the three reproducibility conditions hold. Fixed dice are supported for testing (not available for game play).

• Dice scripts. Scripts in the format documented in docs/A4-script-format.txt are read correctly, and the sample scripts work as intended.

• Black square variants: standard plus two others — Urhedgehog and one of Super Turbo, Slide, or Concrete Block. The game should prompt for the variant at the start.

• Turn variants: standard plus two others — Anarchohedgehog and either Hedgehogs Pushing or Fizzy Lifting. The game should prompt for the variant at the start.

• A playable game. All combinations of rule variants and dice roll modes should work correctly. The P1 features are judged on their own as much as possible, but P1 changes shouldn't break previously working functionality and, conversely, major problems from P0 that keep the game from being played through correctly must be fixed.

• Robustness. Bad input (including invalid seeds and missing or invalid script files) is rejected with a clear message and a reprompt. The program doesn't crash if used incorrectly.

Additional black square and/or turn variants can be implemented for extra credit.

For the other codebase:

• Reproducible dice rolls. The random and chosen seed modes are supported as specified and the three reproducibility conditions hold.

• Robustness. Bad input (including invalid seeds) is rejected with a clear message and a reprompt. The program doesn't crash if used incorrectly. Only the A1 changes are assessed here; problems in the original P0 code don't count against the A1 work.

Code Requirements

For the chosen codebase:

• Coding standards followed — autoformatted with the course's Eclipse formatter settings, standard Java naming conventions (a trailing underscore on instance variables is allowed, but must be used consistently), meaningful names, Javadoc for every public class and method.

• Code review addressed. Each of the detailed findings from the A2 review of the chosen codebase has been resolved: either fixed, or its issue closed with an explanation of why it isn't actually a problem. Other issues are recorded as issues, fixed or labeled deferred. New code doesn't reintroduce problems identified in the review.

• Design. The code organization reflects the design principles discussed in class, design patterns are used where they fit, and the patterns used are implemented correctly. It should be straightforward to add any of the dice roll modes and rule variants in the functionality specification, with a minimum of editing existing code. docs/B-design.txt accurately describes the design, including the reasons for any deliberate tradeoffs.

• Defensive programming and exceptions. User input and script file contents are validated, and checked exceptions are handled meaningfully (no empty catch blocks, and no catching Exception in general).

• Tests. All JUnit tests pass on main. New functionality has tests as described in its test plan, with a rationale for any tests skipped or deferred to manual testing.

For the other codebase:

• A1 code follows the coding standard, and has tests as described in the A1 test plan.

Process Requirements

Follow the steps in each task and the practices in the Team Process section.

• Sequencing. Each deliverable is created at the point specified — in particular, the change impact analysis before any A1 code, test plans before the code they cover, and independent estimates before task sizes and owners are assigned.

• GitHub flow. All code changes are made on branches and merged through pull requests after main has been merged into the branch, main always passes all tests, commits are incremental with meaningful messages, and design refactoring pull requests in Part B are reviewed before merging.

• Test early. Test plans are written before the code they cover and code that isn't covered by tests gets tests for its current behavior before it is refactored.

• Planning and ownership. Each planned task is an issue in the milestone with a size label and an owner, each partner's share is within 40-60% across each of Parts A and B, plan summaries are complete, and actual sizes are recorded in pull request descriptions.

• Team meetings and records. Meetings happen as your team agreed and the team log is kept up to date (with date, attendees, decisions, and open questions for each meeting). Decisions affecting the project are recorded in the log or in issues.

Team Process

These practices apply to all team tasks in both parts; the Version Control and Test Early practices also apply to A1.

Team Kickoff

As part of A0, discuss the following and record notes in a shared document in Google Docs (or similar). Once you've chosen a codebase to work with in A3, move the document to the file docs/team-kickoff.txt.

• Availability. When is each of you realistically available to work on the project, and when not? Include known busy periods during the project, such as exams, other project deadlines, travel, athletics, or work shifts.

• Standing meetings. Pick two regular weekly meeting times (in person or online) that you'll both keep for the whole project. These can be brief meetings, but they shouldn't be skipped. Put them in your calendars now.

• Communication. Which channel will you use (email, text, ...) and when do you each typically check it?

• Work habits. Do you tend to start early or work close to deadlines? Do you prefer long sessions or short ones? Differences are fine; knowing about them lets you plan around them.

• Review turnaround. (for Part B) How soon after a pull request is opened will it be reviewed? Pick a time that fits both of your schedules but no more than 48 hours.

• Goals. What does each of you want to get out of this project? What would a successful outcome look like to you? Are there skills or parts of the work you especially want experience with, or feel less confident about? This can help you split tasks.

Meetings and Team Log

• Meet at least twice a week; short check-ins are fine.

• Keep a running log of meetings in docs/team-log.txt. (Until you've chosen a codebase in A3, use a shared document in Google Docs or similar.) Each entry should have the date, who attended, the decisions made, and open questions. From A3 on, when new tasks are identified, create issues in GitHub and reference them in the log entry (e.g. "created #14-16; moved target date on #9"). Note that issues can include non-code tasks too, such as "write codebase decision memo", "submit individual effort estimates", or "schedule check-in meeting".

Communication and Shared Records

• Day-to-day coordination happens in the channel chosen in your team kickoff (email, text, etc). This is for quick back-and-forth; anything decided that affects the project should be recorded in the team log or in the relevant GitHub issue so it is available to the whole team and doesn't get lost in only one partner's memory.

• Tasks and commitments are tracked as GitHub issues, one per task, including non-code tasks such as drafting a memo or submitting estimates. Each issue has its owner as the assignee and a size: label for its estimate (and joint if applicable), and planned tasks should belong to a milestone with a target date. Close an issue when the task is done.

• Deliverables and records — the team kickoff, team log, plans, memos, reviews, and change impact analyses — are plain text files in the docs/ directory of the appropriate repository. These are the official versions that are assessed.

• Google Docs (or similar) may be used as a scratch space for writing together in real time, such as taking notes during a meeting or drafting a memo. Final versions must be copied into docs/; anything that exists only in a Google Doc doesn't count.

• If you're going to miss a target date, tell your partner before it passes, not after, and update the issue.

Planning and Splitting Work

Most development in a team project happens independently and the goal in dividing up tasks between partners is a fair split.

Steps in the planning process:

• Define the tasks. Create a milestone for the plan and an issue for each task in it, with a title and a description of what the task involves. Leave the assignee and size label blank for now. (Tasks may be specified for you in the handout, or you may need to identify them yourselves.)

• Estimate effort for each task (see Effort Estimation). Assign size: S, size: M, size: L labels to issues reflecting the agreed-on estimates. Address any differences between each partner's independent estimates and how you resolved each one in the plan summary in docs/ (have a separate file for each plan).

• Assign owners. Decide who owns each task (see Ownership), then set each issue's assignee accordingly. To balance the work, count S = 1, M = 2, L = 4 points. Each partner's share should fall between 40% and 60% of the total for each of Part A and Part B. (Doing less on one part can't be made up by doing more on the other.) Within a plan, each partner must own at least one task and joint tasks may make up no more than one-third of the points. Note each partner's point total (count joint tasks as half to each) in the plan summary in docs/.

• Agree on interfaces. Where one task depends on another, agree on the connection point (method names, parameters, behavior) before either of you starts and record it in both issues.

• Reflection. Once the work is done and all of the issues are closed, add a brief reflection (a few sentences to a paragraph) comparing the S/M/L estimates to the recorded actual sizes — where were you off and did the differences discussion predict it?

Effort Estimation

When estimating a task's size, include the time to write its tests. As an approximate guide:

• S (small) tasks are those where the change is well understood (you have a pretty good idea of what to do) and limited to one method or class.
• M (medium) tasks involve a few methods or classes or a design decision or some unknowns that you'll need to work out.
• L (large) tasks span several classes or there is a lot of uncertainty about how best to approach them.

A task bigger than large must be split into smaller tasks. If you are unsure how to decide between two sizes, choose the larger — uncertainty about details of the task is itself a cost since time spent figuring out what to do is part of the task.

When doing effort estimation for a set of issues:

• Estimate independently. Without discussing estimates with your partner, give an S/M/L estimate for each task (by issue number), plus a one-line note on what you think the task involves. Submit your individual estimates on Canvas (PDF) before the team planning meeting.

• Compare. In the planning meeting, discuss every task where your estimates differ: what was each of you picturing, and why? Resolve the difference. This may mean clarifying what the task involves, splitting it, or agreeing on a size. Update the issue description if your understanding of the task changed.

• Record actual sizes. When you open a pull request, include the task's actual size in the pull request description along with a brief explanation if it differs from the estimate (e.g. "Actual: L — validation had many more cases than expected").

The comparison of independent estimates is a key step — the goal of effort estimation is a fair split of work, but just as important is identifying misunderstandings early — if two people give very different estimates for the same task, it is likely that they are picturing different things and that's something to reconcile sooner rather than later.

Ownership

• Owners. Every task has exactly one owner, who is responsible for completing it (with tests) and for opening its pull request. Work is assessed according to ownership (see Assessment).

• Joint tasks. If you plan to pair program a task from start to finish, you may designate it as joint when assigning owners: give it the joint label, and its points count half to each partner. Both partners are responsible for a joint task and must be able to explain it.

Cooperative Programming

• Pair programming is allowed on team tasks. Pairing doesn't change ownership: the owner is still responsible for the task. When pairing, whoever is typing commits and credits their partner by ending the commit message with a blank line followed by Co-authored-by: and the partner's name and email as shown:

        Co-authored-by: Arthur Dent <dent@xyz.edu>

  Use the email associated with the partner's GitHub account so that GitHub credits things properly when showing ownership of commits.

• Swarming means both partners working on one problem together. Use it for design decisions, agreeing on interfaces, and integration problems. Planning meetings are a form of swarming. Implementation is usually split — if you work together on implementation, use pair programming.

Version Control

Follow the GitHub Flow workflow:

• main always contains working code with all tests passing.

• All code changes are done on a branch, one branch per task. Never commit code directly to main. (On the other hand, files in docs/, such as the team log, may be committed directly to main.)

• Always ensure that your local main is up-to-date before creating a new branch.

• Commit incrementally with meaningful messages, as in P0.

• When a task is done, update your local main, merge main into your branch, resolve any conflicts, make sure all tests pass, and open a pull request. In Part A, merge the pull request yourself once it is open. In Part B, merge the pull request for a design refactoring after your partner has reviewed it (see Pull Request Reviews), otherwise merge it yourself once it is open. (This is a stricter version of the workflow from lab 4 — there you only merged main into your branch when GitHub flagged merge conflicts, but just because things merge smoothly doesn't mean nothing broke. Merging main first means you can run tests on the result and make sure everything works before updating the remote repository.)

• When opening a pull request, be sure to include Closes #n in the pull request description so the corresponding issue will be closed automatically when the merge is complete.

Pull Request Reviews

It is common on software teams for every change to be reviewed by another developer before it is merged. Peer review catches bugs and design problems before they reach main, keeps the code consistent, and makes sure more than one person understands each part of the code.

For this project, review is required only for the "refactor first" design refactorings in Part B (where the existing behavior is restructured to use the new design). Other pull requests can still be merged by their author without review, as in Part A.

Turnaround time: pull requests should be reviewed within the turnaround window agreed on in your team kickoff. If a review hasn't happened by then, the author may merge without review; add a comment to the pull request saying so.

The partner wanting to merge:

Opening a pull request for review. Open a pull request as usual, but in the description also summarize what changed and say how you tested it in addition to including which issue it completes (Closes #n). Then select your partner under "Reviewers" in the right sidebar so that GitHub notifies them.

The partner reviewing the pull request:

Reviewing.

• Read the description and the design. Start with the pull request description and the relevant part of docs/B-design.txt, so you know what the change is supposed to do. Find these on GitHub — open the docs directory on the main repository page to find docs/B-design.txt and click on the "Pull requests" tab and then the desired pull request to find the description.

• Get the code so the new structure can be reviewed locally. You can review the changed files on GitHub using the "Files changed" tab on the pull request page, but refactoring moves code around, making it more difficult to use GitHub's comparison view. Instead check out the branch in Eclipse:

  • Fetch the branch. Your partner's branch isn't known to your local project so it first needs to be fetched from GitHub: right-click your project and choose Team → Remote → Fetch from Upstream. If Fetch From Upstream isn't an option, choose Fetch From... instead and then under "Configured remote repository", choose origin for the correct repository and click Next. On the "Fetch Ref Specifications" page, verify that there is an entry with source ref refs/heads/* and destination ref refs/remotes/origin/* (if not, click "Add All Branches Spec"), check "Save specifications in 'origin' configuration" (so that Team → Fetch from Upstream works in the future), and click Finish.

  • Check out the branch. Now that your local project knows about the branch, you can check it out from GitHub: right-click your project and choose Team → Switch To → Other... Expand "Remote Tracking", select origin/branch-name, and click Check Out. When asked, choose "Check out as New Local Branch" and accept the suggested name.

  You should see that the annotation next to the project name in the Package Explorer has been updated to reflect that your project is linked to the desired branch.

• Review. Look for the usual categories from the A2 code review (correctness, standards, tests, readability), focused on the change rather than the whole codebase. In addition, for design refactorings:

  • Does the code match the recorded design?

  • Does it meet the design requirements (see Code Requirements)?

  • Is the existing behavior unchanged? Run all of the JUnit tests. The author should already have done this, but your run catches a common mistake: a new file the author forgot to add to git, which means the branch doesn't compile for anyone else.

  Problems in existing code that the pull request didn't introduce shouldn't be recorded in the pull request and shouldn't block the merge. Mention them to your partner and open an issue if they're worth fixing.

• Comment on GitHub. When you find a problem with the code under review, go to the pull request's "Files changed" tab. Hover over a line and click the + symbol to comment on it; click and drag to comment on several lines. Choose "Start a review" (not "Add single comment") so that your comments are sent together. Keep comments specific and constructive: what the problem is, why it matters, and what you suggest.

• Submit the review. When you are done commenting, click the green "Submit review" button on the "Files changed" tab, write a brief overall summary (for example, whether the code matches the design, and your main concerns, if any), choose "Comment", and click "Submit review". If you found nothing to change, say so in the summary.

• Once done, switch your local project back to main.

The partner wanting to merge:

Responding to a review. Address each review comment by pushing a fix to the branch or by replying to the comment with the reason for disagreement. For smaller points, such as naming, formatting, or minor simplifications, just the reply is sufficient. If you disagree about the design itself, however, talk it over with your partner and agree on what to do.

Once a comment has been addressed, click "Resolve comment" on it; a brief reply when resolving (such as "Fixed" or "Renamed as suggested") is optional but helpful. Once every comment has been resolved, the author merges the pull request. (If main has changed since the pull request was opened, first merge main into the branch again and make sure all tests still pass.) For this project there's no need for a second review unless the fixes significantly changed the design; in that case, talk it over with your partner before merging.

Test Early

Testing should be thought of from the beginning:

• Before refactoring code that isn't covered by tests, write tests that cover what the code currently does. Run all of the tests before and after refactoring.

• When adding new features, write a test plan outlining the scenarios before writing code. The tests themselves can be implemented before or after the associated functionality.

Deliverables and Handin

Deliverables

Your final code is only part of what is assessed. The list below is for reference — each item is created at a specific point as directed in each task's steps above and together they are a record of your process, not just the end result. Process is a big part of this project! Your commit history, handin tags, and Canvas submissions all provide timestamps to document process.

A0 (in your own repository):

• P0-handin tag, unless the repository contains the reference implementation

A1 (individual, in your partner's repository unless noted):

• change impact analysis — on Canvas (PDF), before writing any code
• docs/A1-test-plan.txt — before writing code
• code and JUnit tests, merged through a pull request
• docs/A1-change-impact.txt — the change impact analysis with your reflection added, after merging
• A1-handin tag

A2 (individual, in your partner's repository):

• docs/A2-code-review.txt
• A2-handin tag

A3 (team, in the chosen repository):

• docs/team-kickoff.txt and docs/team-log.txt — copied over from a shared document at the start of A3, with the log kept up to date from then on
• docs/A3-codebase-decision.txt
• independent effort estimates — on Canvas (PDF), each partner, before assigning task sizes and owners
• the "A3 Code Review" milestone and its issues (with size labels and owners) plus the deferred issues
• docs/A3-refactoring-plan.txt — effort estimate differences and their resolutions along with point totals (before starting the refactoring); reflection (when done)
• merged pull requests (with actual sizes in their descriptions) and the resulting code and tests
• A3-handin tag

A4 (team, in the chosen repository):

• independent effort estimates — on Canvas (PDF), each partner, before assigning task sizes and owners
• the "A4 Scripted Dice" milestone and its issues (with size labels and owners)
• docs/A4-scripted-dice-plan.txt — effort estimate differences and their resolutions along with point totals (before starting the implementation); reflection (when done)
• docs/A4-script-format.txt — before the other A4 implementation work begins
• docs/A4-test-plan.txt — each issue's section written before its code
• merged pull requests (with actual sizes in their descriptions) and the resulting code, tests, and sample scripts
• A4-handin tag

B0 (team, in the chosen repository):

• review turnaround time added to docs/team-kickoff.txt, if it wasn't already there

B1 (team, in the chosen repository unless noted):

• individual design sketch — on Canvas (PDF), each partner, before the team design meeting
• docs/B-design.txt and the class diagram (docs/B-design.pdf or .png) — before the check-in meeting, updated afterward if needed
• B1-handin tag

B2 (team, in the chosen repository unless noted):

• independent effort estimates — on Canvas (PDF), each partner, before assigning task sizes and owners
• the "B Variants" milestone and its issues (with size labels and owners)
• docs/B-plan.txt — effort estimate differences and their resolutions along with point totals (before starting implementation); reflection (when done)
• docs/B-test-plan.txt — each issue's section written before its code
• the design refactorings' pull requests, with your partner's reviews, each merged before any new variants for that variation point
• merged pull requests (with actual sizes in their descriptions) and the resulting code and tests
• B2-handin tag

B3 (individual):

• project reflection — hand in a hardcopy
• peer evaluation — on Canvas

Handin

Most of the handin happens along the way, through the tags and Canvas submissions listed in Deliverables. To finish:

• When the whole project is complete, create a tag P1-handin on main in the chosen repository.

• Make sure that I (sbridgeman) have collaborator access to both repositories. (This should have been set up in A0.)

• Complete the peer evaluation on Canvas and hand in a hardcopy of your project reflection (see B3).

Assessment

The course projects together account for 50% of your final grade in this course. There are two distinct components to the project grade:

• Program and deliverable quality. (15%) Does the program correctly implement the specification and are the other deliverables complete and done properly (not just present)? This is assessed individually (on your own work for individual tasks and on your owned tasks for team code) and is graded against the stated program, code, and process requirements — a program missing functionality or crashing on bad input, documentation that's missing or incomplete, or process steps that weren't followed fall short here.

• Skills standards. (35%) Your work also provides evidence towards the following skills standards. These are assessed directly from your deliverables, and some may be followed up on briefly in the handin meeting, where you may be asked to explain a specific choice you made. As with program and deliverable quality, evidence comes from your own work: your individual tasks and the team tasks you own.

  • Change-impact analysis — before changing unfamiliar code, identify the classes and methods the change will affect. [A1 change impact analysis and reflection]

  • Branching and merging and pull requests — do each task on its own branch and merge it through a pull request, with incremental, meaningful commits. [commit history and pull requests for A1, A3, A4, and B2]

  • Merge conflict resolution. [commit history]

  • Identifying real issues in code review — find actual correctness, standards, testing, and readability problems, not just cosmetic ones. [A2 code review, Part B design refactoring reviews]

  • Communicating review feedback — give feedback that is specific, actionable, and constructive. [A2 code review, Part B design refactoring reviews]

  • Project planning — break work into tasks, estimate them, and use the estimates to plan and divide the work. [independent effort estimates, issues and milestones, plan summaries for A3, A4, and Part B]

  • Applying a coding standard. [code]

  • Writing Javadoc — document each public class and method clearly enough that someone could use it without reading its code. [code]

  • Defensive programming — validate input and check for conditions that could make the program fail. [A1 seed input; A4 dice mode selection and script validation]

  • Exception handling — catch and handle exceptions where they can be dealt with meaningfully, including checked exceptions from file input. [A1 seed parsing; A4 script reading]

  • Refactoring code smells. [A3 pull requests]

  • Refactoring safely under a passing test suite — before refactoring, make sure the code's current behavior is covered by tests, and keep all tests passing throughout. [A3 and Part B design refactoring pull requests and commit history]

  • Test planning — plan tests with reasonable coverage of normal, edge, and error cases, and justify what is skipped or deferred. [A1, A4, and Part B test plans]

  • Writing JUnit tests and identifying and testing edge cases. [JUnit tests for A1, A3, A4, and B2]

  • Identifying design flaws — recognize where code violates design principles. [design documents, B3 reflection]

  • Refactoring to improve design — restructure existing code to remove a design flaw without changing its behavior. [Part B design refactoring pull requests]

  • Applying the SOLID principles. [Part B code, B3 reflection]

  • UML class diagrams — draw class diagrams that accurately show classes, their members, and the relationships between them. [individual design sketches, design class diagrams]

  • Implementing design patterns — implement design patterns correctly and where they fit the problem. [Part B code, design documents]

  • Test doubles — use a test double to test code independently of a collaborator whose behavior can't otherwise be controlled. [Part B turn-level tests (fixed dice)]

In addition, teamwork is part of the course engagement grade. Teamwork conduct is assessed through a structured peer evaluation at the end of the project (see B3) with your team log and GitHub activity as supporting evidence.