This site is from a past semester! The current version will be here when the new semester starts.

Week 8 [Fri, Oct 2nd] - Project

iP:

Evaluate two peer iPs Sat, Oct 10th 2359 counted for participation

tP:

Ensure you know tP expectations
Start proper milestone management
Add the first functionality increment

iP

1 Evaluate two peer iPs Sat, Oct 10th 2359 counted for participation

This activity is worth 2x2=4 participation points.

Wait for the email notifying you which iPs are allocated for you to evaluate. When the email is sent out, it will also be announced via module announcements.
Download the latest JAR file of the first iP by following the link provided.
Locate the User Guide of the app by following the link provided.
Open the LumiNUS survey (the one named iP Peer Evaluation 1) that you will be using to submit your evaluation and take note of the things you need to evaluate.
Do a light testing of the app (not more than 10 minutes) to ensure the claimed features actually exist.
Make sure you are using Java 11 to run the jar file (use java -version command to confirm).
If double-clicking the jar file doesn't work, use the java -jar {file_name} command to open it.
Do a quick examination of the code (~ 5 minutes) by following the provided link.
Submit your evaluation using the survey.
Repeat the above steps for the 2nd iP allocated to you (use the survey iP Peer Evaluation 2).

tP: mid-v1.2

Reminder:

Milestone requirements are cumulative. The recommended progress for the mid-milestone is an implicit requirement for the actual milestone unless a milestone requirement overrides a mid-milestone requirement e.g., mid-milestone requires a document to be in a temp format while the actual milestone requires it to be in the proper format. Similarly, a requirement for milestone n is also an implicit requirement for milestone n+1 unless n+1 overrides the n requirement. This means if you miss some requirement at milestone n, you should try to achieve it before milestone n+1 or else it could be noted again as a 'missed requirement' at milestone n+1.

Note that tutors are not allowed to contribute to graded components of your project work. For example, if you are faced with a design decision in your project, the tutor is not allowed to make that decision for you.
Reason: to ensure fairness across teams, and to ensure the work you submit for grading is entirely your own

Following from the above, don't expect the tutor to answer questions that are specific to graded deliverables (e.g., ask which design alternative is better -- that's a decision you need to make yourself). At best, the tutor can channel the question to the professor. However, you can raise such questions in the module forum where the professor can answer the question in a general way that's not unfair to other teams (and other teams can benefit from the answer as well).

How to make project decisions (given your tutor is not going to make them for you)? Here are some tips:

Quickly try out the alternatives. Rather than get into a analysis-paralysis state, quickly prototype the alternatives to figure out which works better.
Go with the team consensus/majority. As most project components are graded by peers, the majority view within the team is a good approximation of how the result will be judged.
Go with the simpler alternative that's good enough for the current iteration. That way, if the decision was the wrong one, you'll find out sooner and the cost will be less. A common rookie pitfall is the temptation to look for an ideal future-proof solution -- usually, there is no such thing. Most alternatives can get the job done, it's just that costs and benefits vary.
Look at what other teams are doing. That will help you detect if you are going in the wrong direction entirely, and also might lead you to more alternatives to consider.
Keep an eye on the results: e.g., Did the design alternative you chose make the code more complex, harder to test, easier to break, harder to modify etc. This will help you decide if you made the right choice.
If you realized you picked the wrong alternative, change if you can. Often, the choice you picked may still be good enough to survive the project. In that case, leave it be, but make a mental note about it (you can even document it in the Developer Guide) for future reference -- that's how you build up experience.

1 Ensure you know tP expectations

If you haven't done so already, make sure you know individual and team expectations of the tP

Functionality Expectations

The expected level of functionality to be added by a 5-person team is roughly the equivalent effort taken to create AB3 functionality. Furthermore, we expect a team to reach that level if each member puts in an effort equivalent to the effort they put into the iP. Some examples meeting that criterion:

Example 1: A fictional contact management app optimized for a specific target user group:
- Existing AB3 features are optimized to the new target user group.
- Person objects are enhanced to contain more details.
- There are a 4-5 new functionality that are specific to the target user group.
Example 2: a FooBar app that keeps track of two different types of entities Foo entities and Bar entities.
- Foo and Bar entities are tightly-connected e.g., a Foo entity can contain Bar entities. Each type is similar to AB3 Person objects in terms of complexity.
- In addition to Creat Read Update DeleteCRUD for Foo and Bar entities, there are a 4-5 FooBar-specific functionality, some of which involves both Foo and Bar entities e.g., link a Foo entity to a Bar entity.

You will get full marks for implementation effort if you meet the expectation stated above. There are no extra marks for exceeding that bar. You are better off spending that effort in improving other aspects of the project.

If you wish to add the following features to your app, we recommend (but not require) you to follow similar features in AB4 in order to reduce the effort required.

One semester ago, we reduced the tP functionality expectations by about 40-50% compared to the previous semesters, in order to reduce your workload. Keep that in mind in case you receive advice about project from seniors who did this module more than one semester ago.

Individual Expectations

Individual Expectations on Implementation

Expectation Contribute to the functional code of the product.
- User-visible features are preferred, but it is not a strict requirement.:
- The enhancement(s) should fit with the rest of the software (and the target user profile) and should have the consent of the team members. You will lose marks if you go 'rogue' and add things that don't fit with the product.

Some examples:

Add a new feature e.g. add the ability to view statistics
Enhance an existing features in a major way e.g. make the command syntax more user friendly and closer to natural language
A redesign of the GUI e.g. make it work like a chat application (note: chat is a form of CLI)
A redesign of the code e.g. Improve the design to improve the code quality.

Tip: Contribute to all aspects of the project e.g. write backend code, frontend code, test code, user documentation, and developer documentation. Reason: If you limit yourself to certain aspects only, you could lose marks allocated for the aspects you did not do. In addition, the final exam assumes that you are familiar with all aspects of the project.
Tip: Do all the work related to your enhancement yourself. Reason: If there is no clear division of who did which enhancement, it will be difficult to divide project credit (or assign responsibility for bugs detected by testers) later.

Tip: Divide the components of the product among team members. Notwithstanding the above, you are still recommended to divide the components of the product among team members so that each team member is in charge of one or more components. While others will be modifying those components to fit their features, your role as the in charge of a component is to guide others modifying that component (reason: you are supposed to be the most knowledgeable about that component) and protect that component from degrading e.g., you can review others' changes to your component and suggest possible changes.

Individual Expectations on Documentation

Objective: showcase your ability to write both user-facing documentation and developer-facing documentation.
Expectation Update the User Guide (UG) and the Developer Guide (DG) parts that are related to the enhancements you added. The minimum requirement is given below. (Reason: Evaluators will not be able to give you marks unless there is sufficient evidence of your documentation skills.)
- UG: 1 or more pages
- DG: 3 or more pages
Tip: If the UG/DG updates for your enhancements are not enough to reach the above requirements, you can make up the shortfall by documenting 'proposed' features and alternative designs/implementations.
Expectation Use at least 2 types of UML diagrams in your DG updates i.e., diagrams you added yourself or those you modified significantly.

Individual Expectations on Testing

Expectation Write some automated tests so that we can evaluate your ability to write tests.

🤔 How much testings is enough? We expect you to decide. You learned different types of testing and what they try to achieve. Based on that, you should decide how much of each type is required. Similarly, you can decide to what extent you want to automate tests, depending on the benefits and the effort required.
There is no requirement for a minimum coverage level. Note that in a production environment you are often required to have at least 90% of the code covered by tests. In this project, it can be less. The weaker your tests are, the higher the risk of bugs, which will cost marks if not fixed before the final submission.

Individual Expectations on Teamwork

Expectation Do an equal share of the team-tasks.

Team-tasks are the tasks that someone in the team has to do.

Here is a non-exhaustive list of team-tasks:

Setting up the GitHub team org/repo
Necessary general code enhancements e.g.,
1. Work related to renaming the product
2. Work related to changing the product icon
3. Morphing the product into a different product
Setting up tools e.g., GitHub, Gradle
Maintaining the issue tracker
Release management
Updating user/developer docs that are not specific to a feature e.g. documenting the target user profile
Incorporating more useful tools/libraries/frameworks into the product or the project workflow (e.g. automate more aspects of the project workflow using a GitHub plugin)

Expectation Carry an equal share of project roles and responsibilities.

Roles indicate aspects you are in charge of and responsible for. E.g., if you are in charge of documentation, you are the person who should allocate which parts of the documentation is to be done by who, ensure the document is in right format, ensure consistency etc.

This is a non-exhaustive list; you may define additional roles.

Team lead: Responsible for overall project coordination.
Documentation (short for ‘in charge of documentation’): Responsible for the quality of various project documents.
Testing: Ensures the testing of the project is done properly and on time.
Code quality: Looks after code quality, ensures adherence to coding standards, etc.
Deliverables and deadlines: Ensure project deliverables are done on time and in the right format.
Integration: In charge of versioning of the code, maintaining the code repository, integrating various parts of the software to create a whole.
Scheduling and tracking: In charge of defining, assigning, and tracking project tasks.
[Tool ABC] expert: e.g. Intellij expert, Git expert, etc. Helps other team member with matters related to the specific tool.

In charge of[Component XYZ]: e.g. In charge of Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that component well, and review changes done to that component in v1.3-v1.4.

Ensure each of the important roles are assigned to one person in the team. It is OK to have a 'backup' for each role, but for each aspect there should be one person who is unequivocally the person responsible for it. Reason: when everyone is responsible for everything, no one is.

Expectation Review each others work. Reason: reviewing skills is a learning outcome, and it is mutually beneficial.

Team Expectations

Expectation Preserve product integrity i.e. ensure,
1. features fit together to form a cohesive product,
2. documentation follows a consistent style and presents a cohesive picture to the reader, and
3. final project demo presents a cohesive picture to the audience.
Expectation Maintain product quality i.e. prevent breaking other parts of the product as it evolves. Note that bugs local to a specific feature will be counted against the author of that feature. However, if a new enhancement breaks the entire product, the whole team will have to share the penalty.
Expectation Manage the project i.e. ensure workflow, code maintenance, integration, releases, etc. are done smoothly.

Individual Expectations

Individual Expectations on Implementation

Expectation Contribute to the functional code of the product.
- User-visible features are preferred, but it is not a strict requirement.:
- The enhancement(s) should fit with the rest of the software (and the target user profile) and should have the consent of the team members. You will lose marks if you go 'rogue' and add things that don't fit with the product.

Some examples:

Add a new feature e.g. add the ability to view statistics
Enhance an existing features in a major way e.g. make the command syntax more user friendly and closer to natural language
A redesign of the GUI e.g. make it work like a chat application (note: chat is a form of CLI)
A redesign of the code e.g. Improve the design to improve the code quality.

Tip: Contribute to all aspects of the project e.g. write backend code, frontend code, test code, user documentation, and developer documentation. Reason: If you limit yourself to certain aspects only, you could lose marks allocated for the aspects you did not do. In addition, the final exam assumes that you are familiar with all aspects of the project.
Tip: Do all the work related to your enhancement yourself. Reason: If there is no clear division of who did which enhancement, it will be difficult to divide project credit (or assign responsibility for bugs detected by testers) later.

Tip: Divide the components of the product among team members. Notwithstanding the above, you are still recommended to divide the components of the product among team members so that each team member is in charge of one or more components. While others will be modifying those components to fit their features, your role as the in charge of a component is to guide others modifying that component (reason: you are supposed to be the most knowledgeable about that component) and protect that component from degrading e.g., you can review others' changes to your component and suggest possible changes.

Individual Expectations on Documentation

Objective: showcase your ability to write both user-facing documentation and developer-facing documentation.
Expectation Update the User Guide (UG) and the Developer Guide (DG) parts that are related to the enhancements you added. The minimum requirement is given below. (Reason: Evaluators will not be able to give you marks unless there is sufficient evidence of your documentation skills.)
- UG: 1 or more pages
- DG: 3 or more pages
Tip: If the UG/DG updates for your enhancements are not enough to reach the above requirements, you can make up the shortfall by documenting 'proposed' features and alternative designs/implementations.
Expectation Use at least 2 types of UML diagrams in your DG updates i.e., diagrams you added yourself or those you modified significantly.

Individual Expectations on Testing

Expectation Write some automated tests so that we can evaluate your ability to write tests.

Individual Expectations on Teamwork

Expectation Do an equal share of the team-tasks.

Team-tasks are the tasks that someone in the team has to do.

Here is a non-exhaustive list of team-tasks:

Setting up the GitHub team org/repo
Necessary general code enhancements e.g.,
1. Work related to renaming the product
2. Work related to changing the product icon
3. Morphing the product into a different product
Setting up tools e.g., GitHub, Gradle
Maintaining the issue tracker
Release management
Updating user/developer docs that are not specific to a feature e.g. documenting the target user profile
Incorporating more useful tools/libraries/frameworks into the product or the project workflow (e.g. automate more aspects of the project workflow using a GitHub plugin)

Expectation Carry an equal share of project roles and responsibilities.

This is a non-exhaustive list; you may define additional roles.

Team lead: Responsible for overall project coordination.
Documentation (short for ‘in charge of documentation’): Responsible for the quality of various project documents.
Testing: Ensures the testing of the project is done properly and on time.
Code quality: Looks after code quality, ensures adherence to coding standards, etc.
Deliverables and deadlines: Ensure project deliverables are done on time and in the right format.
Integration: In charge of versioning of the code, maintaining the code repository, integrating various parts of the software to create a whole.
Scheduling and tracking: In charge of defining, assigning, and tracking project tasks.
[Tool ABC] expert: e.g. Intellij expert, Git expert, etc. Helps other team member with matters related to the specific tool.

In charge of[Component XYZ]: e.g. In charge of Model, UI, Storage, etc. If you are in charge of a component, you are expected to know that component well, and review changes done to that component in v1.3-v1.4.

Expectation Review each others work. Reason: reviewing skills is a learning outcome, and it is mutually beneficial.

2 Start proper milestone management

Set up the issue tracker as described in the panel below, if you haven't done so already.

tP Issue Tracker Setup

We recommend you configure the issue tracker of the tP team repo as follows:

Delete existing labels and add the following labels.
Issue type labels are useful from the beginning of the project. The other labels are needed only when you start implementing the features.

Issue type labels:

type.Epic : A big feature which can be broken down into smaller stories e.g. search
type.Story : A user story
type.Enhancement: An enhancement to an existing story
type.Task (or type.Chore) : Something that needs to be done, but not a story, bug, or an epic. e.g. Move testing code into a new folder)
type.Bug : A bug

Priority labels:

priority.High : Must do
priority.Medium : Nice to have
priority.Low : Unlikely to do

Bug Severity labels:

severity.VeryLow : A flaw that is purely cosmetic and does not affect usage e.g., a typo/spacing/layout/color/font issues in the docs or the UI that doesn't affect usage.
severity.Low : A flaw that is unlikely to affect normal operations of the product. Appears only in very rare situations and causes a minor inconvenience only.
severity.Medium : A flaw that causes occasional inconvenience to some users but they can continue to use the product.
severity.High : A flaw that affects most users and causes major problems for users. i.e., makes the product almost unusable for most users.

When applying for documentation bugs, replace user with reader.

Create following milestones : v1.1, v1.2, v1.3, v1.4
You may configure other project settings as you wish. e.g. more labels, more milestones

Start proper schedule tracking and milestone management as explained in the panel below.

tP Project Schedule Tracking

In general, use the issue tracker (Milestones, Issues, PRs, Tags, Releases, and Labels) for assigning, scheduling, and tracking all noteworthy project tasks, including user stories. Update the issue tracker regularly to reflect the current status of the project. You can also use GitHub's Projects feature to manage the project, but keep it linked to the issue tracker as much as you can.

Using Issues:

Record each of the user stories you plan to deliver as an issue in the issue tracker. e.g.,

You can break the user story into issue subject and description in this way:

title	`As a user I can add a deadline`
Description	`... so that I can keep track of my deadlines`

Alternatively, you can put the entire user story in the description.

title	`Add deadline`
Description	`As a user I can so that I can keep track of my deadlines`

In both cases, apply the type.Story label.

Assign the type.* and priority.* labels to those issues.
Formalize the project plan by assigning relevant issues to the corresponding milestone.
Define project tasks as issues. When you start implementing a user story (or a feature), break it down to smaller tasks if necessary. Define reasonable sized, standalone tasks. Create issues for each of those tasks so that they can be tracked.
- A typical task should be small enough for one person to do in a few hours. eg.,
  - Bad (reasons: not a one-person task, not small enough): Write the Developer Guide
  - Good: Update class diagram in the Developer Guide for v1.4
- There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,
  - Bad:Implementing parser (reason: too big).
  - Good:Implementing parser support for adding of floating tasks
- Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.
- Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser
  - Omit redundant details. In some cases, the issue title is enough to describe the task. In that case, no need to repeat it in the issue description. There is no need for well-crafted and detailed descriptions for tasks. A minimal description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.
Assign tasks (i.e., issues) to the corresponding team members using the assignees field. Normally, there should be some ongoing tasks and some pending tasks against each team member at any point.

Using Milestones:

Given below are the conditions to satisfy for a milestone to be considered properly managed:

Planning a Milestone (to do within the first week of the iteration):

Issues assigned to the milestone, team members assigned to issues: Used GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones. Ensured issues are assigned to team members. Note that you can change the milestone plan along the way as necessary.
Deadline set for the milestones (in the GitHub milestone). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.

Wrapping up a Milestone:

A working product tagged with the correct tag (e.g. v1.3) and is pushed to the main repo or a product release done on GitHub (example).
CI passing for the version tagged/released.
Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone. Incomplete issues/PRs should be moved to a future milestone.
Milestone closed.

Try to achieve all milestone requirements, but do not fret if you miss a few. You will get full marks as long as you achieve about 60% of the milestone requirements on average. Yes, that's a pretty low bar, but we have set it low in order to reduce workload and stress. Ideally, you should achieve close to 80-90%.

3 Add the first functionality increment

Add functionality in small steps, aiming to deliver the first working version of your product by the mid-milestone (i.e., in one week), and v1.2 at the end of this iteration (i.e., in two weeks).
If you split the iteration into two smaller iterations of one-week each (recommended), name the first one v1.2 and the second one v1.2b so that the dashboard can track them accurately.
From this point onwards each member is expected to contribute the amount of code does not matter; even small contributions are acceptablesome code to each v1.3, v1.4 milestone, preferably each week; only merged code is considered as contributions The ability to deliver code incrementally is an important learning outcome of this module because incremental delivery, among other things, improves the visibility of your work.(Reason).