[Direction 1] Optimize AddressBook for a more specific target user group:

[Direction 2] Morph AddressBook into a different product: Given that AddressBook is a generic app that manages a type of elements (i.e. contacts), you can use it as a starting point to create an app that manages something else.
❗️ This is a high-risk high-reward option because morphing requires extra work but a morphed product may earn more marks than an optimized product of similar complexity.

For either direction, you need to define a target user profile and a value proposition:

• Target user profile: Define a very specific target user profile.
  💡 We required you narrow down the target user profile  as opposed to trying to make it as general as possible. Here is an example direction of narrowing down target user: anybody → teachers → university teachers → tech savvy university teachers → CS2103 instructors.
  ❗️ Be careful not to contradict given project constraints when defining the user profile  e.g. the target user should still prefer typing over mouse actions.

• Value proposition: Define a clear value proposition  what problem does the product solve? how does it make the the user's life easier that matches the target user profile.

It is expected that your product will be optimized for those specific target users  i.e., add features that are especially/only applicable for target users (to make the app especially attractive to them). To add to the example above, there can be features that are applicable to CS2103 instructors only, such as the ability to navigate to a student's project on GitHub
💡 Your project will be graded based on how well the features match the target user profile and how well the features fit-together.

v1.0 Documentation

Objective: To analyze requirements, conceptualize the next version of the product (i.e. v2.0), and document it.

Step 1 : Decide project direction, target user profile, and problem addressed

Discuss with your team members and decide your project direction, target user profile, and the value proposition of the product, as described in [Admin » Project Scope]

Step 2 : Brainstorm user stories

Get together with your team members and brainstorm for user stories  for the v2.0 of the product. Note that in the module project you will deliver only up to v1.5 but here you should consider up to v2.0 (i.e. beyond the module).

• It is ok to have more user stories than you can deliver in the project. Aim to create at least 30 user stories. Include all 'obvious' ones you can think of but also look for 'non obvious' ones that you think are likely to be missed by other teams.

• Refer [Textbook » Specifying Requirements → UserStories → Usage → (section) Tips] for tips on how to use user stories in this task.

• You can write each user story in a piece of paper (e.g. yellow sticky note, index card, or just pieces of paper about the size of a playing card). Alternatively you can use an online tool (some examples given in [Textbook » Specifying Requirements → UserStories → Usage → (panel) Tool Examples ]).
  

• Note that you should not 'evaluate' the value of user stories while doing the above.  Reason: an important aspect of brainstorming is not judging the ideas generated.

Requirements → Specifying Requirements → User Stories →

Introduction

User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. _{[Mike Cohn]}

A common format for writing user stories is:

User story format: As a {user type/role} I can {function} so that {benefit}

📦 Examples (from a Learning Management System):

1. As a student, I can download files uploaded by lecturers, so that I can get my own copy of the files
2. As a lecturer, I can create discussion forums, so that students can discuss things online
3. As a tutor, I can print attendance sheets, so that I can take attendance during the class

We can write user stories on index cards or sticky notes, and arrange on walls or tables, to facilitate planning and discussion. Alternatively, we can use a software (e.g., GitHub Project Boards, Trello, Google Docs, ...) to manage user stories digitally.

^{[credit: https://www.flickr.com/photos/jakuza/2682466984/]}

^{[credit: https://www.flickr.com/photos/jakuza/with/2726048607/]}

^{[credit: https://commons.wikimedia.org/wiki/File:User_Story_Map_in_Action.png]}

• a. They are based on stories users tell about similar systems
• b. They are written from the user/customer perspective
• c. They are always written in some physical medium such as index cards or sticky notes

• a. Reason: Despite the name, user stories are not related to 'stories' about the software.
• b.
• c. Reason: It is possible to use software to record user stories. When the team members are not co-located this may be the only option.

Critique the following user story taken from a software project to build an e-commerce website.

As a developer, I want to use Python to implement the software, so that we can resue existing Python modules.

Refer to the definition of a user story.

User story: User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. _{[Mike Cohn]}

This user story is not written from the perspective of the user/customer.

Bill wants you to build a Human Resource Management (HRM) system. He mentions that the system will help employees to view their own leave balance. What are the user stories you can extract from that statement?

Remember to follow the correct format when writing user stories.

User story format: As a {user type/role} I can {function} so that {benefit}

As an employee, I can view my leave balance, so that I can know how many leave days I have left.

Note: the {benefit} part may vary as it is not specifically mentioned in the question.

Step 3: Prioritize the user stories

Suggested workflow:

• Take one user story at a time and get team member opinions about it.

• Based on the team consensus, put the story (i.e. the piece of paper) onto one of these three piles:

  • Must-Have : The product will be practically useless to the target user without this feature.
  • Nice-To-Have : The target user can benefit from this user story significantly but you are not certain if you'll have time to implement it.
  • Not-Useful : No significant benefit to the target user, or does not fit into the product vision.

• If using physical paper to record user stories: After all stories have been put in the above three piles, you can make a record of which stories are in the three piles.

Step 4: Record v2.0 Requirements in the Developer Guide

Based on your user story categorization in step 1, given project requirements, and the current state of the product, select which user stories you are likely to include in v2.0.

Update the following pages of the Developer Guide:

• Target user profile, value proposition, and user stories: Update the target user profile and value proposition to match the project direction you have selected. Give a list of the user stories (and update/delete existing ones, if applicable), including priorities. This can include user stories considered but will not be included in the final product.
• Use cases: Give use cases (textual form) for a few representative user stories that need multiple steps to complete. e.g. Adding a tag to a person (assume the user needs to find the person first)
• Non-functional requirements:
  Note: Many of the project constraints mentioned above are NFRs. You can add more. e.g. performance requirements, usability requirements, scalability requirements, etc.
• Glossary: Define terms that are worth defining.
• [Optional] Product survey: Explore a few similar/related products and describe your findings i.e. Pros, cons, (from the target user's point of view).

Introduction

🏆 Can explain use cases

Use Case: A description of a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an actor.[ 📖 : uml-user-guideThe Unified Modeling Language User Guide, 2e, G Booch, J Rumbaugh, and I Jacobson ]

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

A use case describes an interaction between the user and the system for a specific functionality of the system.

• System: ATM
• Actor: Customer
• Use Case: Check account balance
  1. User inserts an ATM card
  2. ATM prompts for PIN
  3. User enters PIN
  4. ATM prompts for withdrawal amount
  5. User enters the amount
  6. ATM ejects the ATM card and issues cash
  7. User collects the card and the cash.

• System: A Learning Management System (LMS)
• Actor: Student
• Use Case: Upload file
  1. Student requests to upload file
  2. LMS requests for the file location
  3. Student specifies the file location
  4. LMS uploads the file

UML includes a diagram type called use case diagrams that can illustrate use cases of a system visually, providing a visual ‘table of contents’ of the use cases of a system. In the example below, note how use cases are shown as ovals and user roles relevant to each use case are shown as stick figures connected to the corresponding ovals.

Unified Modeling Language (UML) is a graphical notation to describe various aspects of a software system. UML is the brainchild of three software modeling specialists James Rumbaugh, Grady Booch and Ivar Jacobson (also known as the Three Amigos). Each of them has developed their own notation for modeling software systems before joining force to create a unified modeling language (hence, the term ‘Unified’ in UML). UML is currently the de facto modeling notation used in the software industry.

Use cases capture the functional requirements of a system.

Identifying

🏆 Can use use cases to list functional requirements of a simple system

A use case is an interaction between a system and its actors.

Actors in Use Cases

Actor: An actor (in a use case) is a role played by a user. An actor can be a human or another system. Actors are not part of the system; they reside outside the system.

📦 Some example actors for a Learning Management System

• Actors: Guest, Student, Staff, Admin, ExamSys, LibSys.

A use case can involve multiple actors.

• Software System: LearnSys
• Use case: UC01 conduct survey
• Actors: Staff, Student

An actor can be involved in many use cases.

• Software System: LearnSys
• Actor: Staff
• Use cases: UC01 conduct survey, UC02 Set Up Course Schedule, UC03 Email Class, ...

A single person/system can play many roles.

• Software System: LearnSys
• Person: a student
• Actors (or Roles): Student, Guest, Tutor

Many persons/systems can play a single role.

• Software System: LearnSys
• Actor(or role) : Student
• Persons that can play this role : undergraduate student, graduate student, a staff member doing a part-time course, exchange student

Use cases can be specified at various levels of detail.

📦 Consider the three use cases given below. Clearly, (a) is at a higher level than (b) and (b) is at a higher level than (c).

• System: LearnSys
• Use cases:
  a. Conduct a survey
  b. Take the survey
  c. Answer survey question

While modeling user-system interactions,

💡 Start with high level use cases and progressively work toward lower level use cases.

💡 Be mindful at which level of details you are working on and not to mix use cases of different levels.

Consider a simple movie ticket vending machine application. Every week, the theatre staff will enter the weekly schedule as well as ticket price for each show. A customer sees the schedule and the ticket price displayed at the machine. There is a slot to insert money, a keypad to enter a code for a movie, a code for the show time, and the number of tickets. A display shows the customer's balance inside the machine. A customer may choose to cancel a transaction before pressing the “buy” button. Printed tickets can be collected from a slot at the bottom of the machine. The machine also displays messages such as "Please enter more money”, “Request fewer tickets" or "SOLD OUT!”. Finally, a "Return Change" button allows the customer to get back his unspent money.

Draw a use case diagram for the above requirements.

Note that most of the details in the description are better given as part of the use case description rather than as low-level use cases in the diagram.

A software house wishes to automate its Quality Assurance division.

The system is to be used by Testers, Programmers and System Administrators. Only an administrator can create new users and assign tasks to programmers. Any tester can create a bug report, as well as set the status of a bug report as ‘closed’. Only a programmer can set the state of a bug report to ‘fixed’, but a programmer cannot set the status of a bug report to ‘closed’. Each tester is assigned just one task at a time. A task involves testing of a particular component for a particular customer. Tester must document the bugs they find. Each bug is given a unique identifier. Other information recorded about the bug is component id, severity, date and time reported, programmer who is assigned to fix it, date fixed, date retested and date closed. The system keeps track of which bugs are assigned to which programmer at any given time. It should be able to generate reports on the number of bugs found, fixed and closed e.g. number of bugs per component and per customer; number of bugs found by a particular tester ; number of bugs awaiting to be fixed; number of bugs awaiting to be retested; number of bugs awaiting to be assigned to programmers etc.

Develop a use case diagram to capture their requirements given below.

Explanation: The given description contains information not relevant to use case modeling. Furthermore, the description is not enough to complete the use case diagram All these are realities of real projects. However, the process of trying to create this use case diagram prompts us to investigate issues such as:

• Is ‘edit bug report’ a use case or editing the bug report is covered by other use cases such as those for setting the status of bug reports? If it is indeed a separate use case, who are the actors of that use case?
• Does ‘assign task’ simply means ‘assign bug report’ or is there any other type of tasks?
• There was some mention about Customers and Components. Does the system have to support use cases for creating and maintaining details about those entities? For example, should we have a ‘create customer record’ use case?
• Which actors can perform the ‘generate report’ use case? Are reports generated automatically by the system at a specific time or generated ‘on demand’ when users request to view them? Do we have to treat different types of reports as different use cases (in case some types of reports are restricted to some types of users)? The above diagram assumes (just for illustration) that the report is generated on demand and only the system admin can generate any report.

Details

🏆 Can specify details of a use case in a structured format

Writing use case steps

The main body of the use case is the sequence of steps that describes the interaction between the system and the actors. Each step is given as a simple statement describing who does what.

📦 An example of the main body of a use case.

1. Student requests to upload file
2. LMS requests for the file location
3. Student specifies the file location
4. LMS uploads the file

A use case describes only the externally visible behavior, not internal details, of a system i.e. should not mention give details that are not part of the interaction between the user and the system.

📦 This example use case step refers to behaviors not externally visible .

1. LMS saves the file into the cache and indicates success.

A step gives the intention of the actor (not the mechanics). That means UI details are usually omitted. The idea is to leave as much flexibility to the UI designer as possible. That is, the use case specification should be as general as possible (less specific) about the UI.

❌ User right-clicks the text box and chooses ‘clear’  : this contains UI-specific details and is not a good use case step)

✅ User clears the input  : this is better because it omits UI-specific details

This is how you can include repetitive steps in a scenario.

Software System: Square game Use case: UC02 - Play a Game Actors: Player (multiple players)

1. A Player starts the game.
2. SquareGame asks for player names.
3. Each Player enters his own name.
4. SquareGame shows the order of play.
5. SquareGame prompts for the current Player to throw die.
6. Current Player adjusts the throw speed.
7. Current Player triggers the die throw.
8. Square Game shows the face value of the die.
9. Square Game moves the Player's piece accordingly.
   Steps 5-9 are repeated for each Player, and for as many rounds as required until a Player reaches the 100th square.
10. Square Game shows the Winner.

  Use case ends.

The Main Success Scenario (MSS) describes the most straightforward interaction for a given use case, which assumes that nothing goes wrong. This is also called the Basic Course of Action or the Main Flow of Events of a use case.

• System: Online Banking System (OBS)
• Use case: UC23 - Transfer Money
• Actor: User
• MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. OBS transfers the money and displays the new account balance.
  6. Use case ends.

Note how the MSS assumes that all entered details are correct and ignores problems such as timeouts, network outages etc. Fro example, MSS does not tell us what happens if the user enters an incorrect data.

Extensions are "add-on"s to the MSS that describe exceptional/alternative flow of events. They describe variations of the scenario that can happen if certain things are not as expected by the MSS. Extensions appear below the MSS.

📦 This example adds some extensions to the use case in the previous example.

• System: Online Banking System (OBS)
• Use case: UC23 - Transfer Money
• Actor: User
• MSS:
  1. User chooses to transfer money.
  2. OBS requests for details of the transfer.
  3. User enters the requested details.
  4. OBS requests for confirmation.
  5. OBS transfers the money and displays the new account balance.
  6. Use case ends.
• Extensions:
  1. 3a. OBS detects an error in the entered data.
     1. 3a1. OBS requests for the correct data.
     2. 3a2. User enters new data.
     3. Steps 3a1-3a2 are repeated until the data entered are correct.
     4. Use case resumes from step 4.
  2. 3b. User requests to effect the transfer in a future date.
     1. 3b1. OBS requests for confirmation.
     2. 3b2. User confirms future transfer.
     3. Use case ends.
  3. *a. At any time, User chooses to cancel the transfer.
     1. *a1. OBS requests to confirm the cancellation.
     2. *a2. User confirms the cancellation.
     3. Use case ends.
  4. *b. At any time, 120 seconds lapse without any input from the User.
     1. *b1. OBS cancels the transfer.
     2. *b2. OBS informs the User of the cancellation.
     3. Use case ends.

Note that the numbering style is not a universal rule but a widely used convention. Based on that convention,

• either of the extensions marked 3a. and 3b. can happen just after step 3 of the MSS.
• the extension marked as *a. can happen at any step (hence, the *).

When separating extensions from the MSS, keep in mind that the MSS should be self-contained. That is, the MSS should give us a complete usage scenario.

Also note that it is not useful to mention events such as power failures or system crashes as extensions because the system cannot function beyond such catastrophic failures.

In use case diagrams you can use the << extend >> arrows to show extensions. Note the direction of the arrow is from the extension to the use case it extends and the arrow uses a dashed line.

A use case can include another use case. Underlined text is commonly used to show an inclusion of a use case.

📦 This use case includes two other use cases, one in step 1 and one in step 2.

• Software System: LearnSys
• Use case: UC01 - Conduct Survey
• Actors: Staff, Student
• MSS:
  1. Staff creates the survey (UC44).
  2. Student completes the survey (UC50).
  3. Staff views the survey results.
  4. Use case ends.

Inclusions are useful,

• when you don't want to clutter a use case with too many low-level steps.
• when a set of steps is repeated in multiple use cases.

We use a dotted arrow and a << include >> annotation to show use case inclusions in a use case diagram. Note how the arrow direction is different from the << extend >> arrows.

Preconditions specify the specific state we expect the system to be in before the use case starts.

• Software System: Online Banking System
• Use case: UC23 - Transfer Money
• Actor: User
• Preconditions: User is logged in.
• MSS:
  1. User chooses to transfer money.
  2. OBS requests for details for the transfer.
  3. ...

Guarantees specify what the use case promises to give us at the end of its operation.

• Software System: Online Banking System
• Use case: UC23 - Transfer Money
• Actor: User
• Preconditions: User is logged in.
• Guarantees:
  • Money will be deducted from the source account only if the transfer to the destination account is successful
  • The transfer will not result in the account balance going below the minimum balance required.
• MSS:
  1. User chooses to transfer money.
  2. OBS requests for details for the transfer.
  3. ...

Complete the following use case (MSS, extensions, etc.). Note that you should not blindly follow how the existing EZ-Link machine operates because it will prevent you from designing a better system. You should consider all possible extensions without complicating the use case too much.

• System: EZ-Link machine
• Use case: UC2 top-up EZ-Link card
• Actor: EZ-Link card user

• System: EZ-Link machine (those found at MRTs)
• Use case: UC2 top-up EZ-Link card
• Actor: EZ-Link card user
• Preconditions: All hardware in working order.
• Guarantees: MSS → the card will be topped-up.
• MSS:
  1. User places the card on the reader.
  2. System displays card details and prompts for desired action.
  3. User selects top-up.
  4. System requests for top-up details (amount, payment option, receipt required?).
  5. User enters details.
  6. System processes cash payment (UC02) or NETS payment (UC03).
  7. System updates the card value.
  8. System indicates transaction as completed.
  9. If requested in step 5, system prints receipt.
  10. User removes the card.
  11. Use case ends.
• Extensions:
  1. *a. User removed card or other hardware error detected.
     1. *a1. System indicates the transaction has been aborted.
     2. Use case ends.

Notes:

• We assume that the only way to cancel a transaction is by removing the card.
• By not breaking step 4 into further steps, we avoid committing to a particular mechanism to enter data. For example, we are free to accept all data in one screen.
• In step 5, we assume that the input mechanism does not allow any incorrect data.

• System: EZ-Link machine
• Use case: UC03 process NETS payment
• Actor: EZ-Link card user
• Preconditions: A transaction requiring payment is underway.
• Guarantees: MSS → Transaction amount is transferred from user account to EZ-Link company account.
• MSS:
  1. System requests to insert ATM card.
  2. User inserts the ATM card.
  3. System requests for PIN.
  4. User enters PIN.
  5. System reports success.
  6. Use case ends.
• Extensions:
  1. 2a. Unacceptable ATM card (damaged or inserted wrong side up).
     1. ...
  2. 4a. Wrong PIN.
     1. ...
  3. 4b. Insufficient funds.
     1. ...
  4. *a. Connection to the NETS gateway is disrupted.
     1. ...

Note: UC02 can be written along similar lines.

Complete the following use case (MSS, extensions, etc.).

• System: LearnSys (an online Learning Management System)
• Use case: UC01 reply to post in the forum
• Actor: Student

• System: LearnSys
• Use case: UC01 reply to post in the forum
• Actor: Student
• Preconditions: Student is logged in and has permission to post in the forum. The post to which the Student replies already exists.
• MSS:
  1. Student chooses to reply to an existing post.
  2. LearnSys requests the user to enter post details.
  3. Student enters post details.
  4. Student submits the post.
  5. LearnSys displays the post.
  6. Use case ends.
• Extensions:
  1. *a. Internet connection goes down.
     1. ...
  2. *b. LearnSys times out
     1. ...
  3. 3a. Student chooses to ‘preview’ the post.
     1. 3a1. LearnSys shows a preview.
     2. 3a2. User chooses to go back to editing.
     3. Use case resumes at step 3.
  4. 3b. Student chooses to attach picture/file
     1. ...
  5. 3c. Student chooses to save the post as a draft.
     1. 3c1. LearnSys confirms draft has been saved.
     2. Use case ends.
  6. 3d. Student chooses to abort the operation.
     1. ...
  7. 4a. The post being replied to is deleted by the owner while the reply is being entered.
     1. ...
  8. 4b. Unacceptable data entered.
     1. ...

Which of these cannot appear as part of a use case description?

• a. Use case identifier
• b. Preconditions
• c. Guarantees
• d. References to another use case
• e. Main Success Scenario
• f. Performance requirements
• g. Extensions
• h. Inclusions

(f)

Explanation: Performance requirements are non-functional requirements. They are not captured in use cases.

Identify problems with this use case description.

• System: EZ-Link machine (those found at MRTs)
• Use case: UC2 top-up EZ-Link card
• Actor: EZ-Link card user
• Preconditions: All hardware in working order.
• Guarantees: If MSS completes at least until step 7, the card will be topped-up.
• MSS:
  1. User places the card on the reader.
  2. System displays card details and prompts for desired action.
  3. User selects top-up.
  4. System requests for top-up details (amount, payment option, receipt required?).
  5. User enters details.
  6. System processes cash payment (UC02) or NETS payment (UC03).
  7. System updates the card value.
  8. System indicates transaction as completed.
  9. If requested in step 5, system prints receipt.
  10. User removes the card.
  11. Use case ends.
• Extensions:
  1. *a. User removed card or other hardware error detected.
     1. *a1. System indicates the transaction has been aborted.
     2. Use case ends.

• a. It does not consider ‘system crash’ scenario.
• b. It does not contain enough UI details.
• c. The extension given is in fact an inclusion.
• d. No post conditions are given.
• e. ‘Use case ends’ is duplicated.

None.

Explanation: Catastrophic failures such as ‘system crash’ need not be included in a use case. A use case is not supposed to contain UI details. Post conditions are optional. It is not a problem to have multiple exit points for a use case.

Usage

🏆 Can optimize the use of use cases

You can use actor generalization in use case diagrams using a symbol similar to that of UML notation for inheritance.

📦 In this example, actor Blogger can do all the use cases the actor Guest can do, as a result of the actor generalization relationship given in the diagram.

💡 Do not over-complicate use case diagrams by trying to include everything possible. A use case diagram is a brief summary of the use cases that is used as a starting point. Details of the use cases can be given in the use case descriptions.

Some include ‘System’ as an actor to indicate that something is done by the system itself without being initiated by a user or an external system.

📦 The diagram below can be used to indicate that the system generates daily reports at midnight.

However, others argue that only use cases providing value to an external user/system should be shown in the use case diagram. For example, they argue that ‘view daily report’ should be the use case and generate daily report is not to be shown in the use case diagram because it is simply something the system has to do to support the view daily report use case.

We recommend that you follow the latter view (i.e. not to use System as a user). Limit use cases for modeling behaviors that involve an external actor.

UML is not very specific about the text contents of a use case. Hence, there are many styles for writing use cases. For example, the steps can be written as a continuous paragraph. Use cases should be easy to read. Note that there is no strict rule about writing all details of all steps or a need to use all the elements of a use case.

There are some advantages of documenting system requirements as use cases:

• Because they use a simple notation and plain English descriptions, they are easy for users to understand and give feedback.
• They decouple user intention from mechanism (note that use cases should not include UI-specific details), allowing the system designers more freedom to optimize how a functionality is provided to a user.
• Identifying all possible extensions encourages us to consider all situations that a software product might face during its operation.
• Separating typical scenarios from special cases encourages us to optimize the typical scenarios.

One of the main disadvantages of use cases is that they are not good for capturing requirements that does not involve a user interacting with the system. Hence, they should not be used as the sole means to specify requirements.

What are the advantages of using use cases (the textual form) for requirements modelling?

• a. They can be fairly detailed but still natural enough for users for users to understand and give feedback.
• b. The UI-independent nature of use case specification allows the system designers more freedom to decide how a functionality is provided to a user.
• c. Extensions encourage us to consider all situations a software product might face during its operations.
• d. They encourage us to identify and optimize the typical scenario of usage over exceptional usage scenarios.

(a) (b) (c) (d)

Which of these are correct?

• a. Use case are not very suitable for capturing non-functional requirements.
• b. Use case diagrams are less detailed than textual use cases.
• c. Use cases are better than user stories.
• d. Use cases can be expressed at different levels of abstraction.

(a)(b)(d)

Explanation: It is not correct to say one format is better than the other. It depends on the context.

Suggested length: Follow the existing user guide and developer guides in terms of the level of details.

Submission:

1. One team member: Set up the team org and team repo for your phase B team if you haven't done that already.

2. Divide among yourselves who will update which parts of the Developer guide.
3. Update the team repo. Recommended: follow the forking workflow.

Project Management → Revision Control →

Forking Flow

In the forking workflow, the 'official' version of the software is kept in a remote repo designated as the 'main repo'. All team members fork the main repo create pull requests from their fork to the main repo.

To illustrate how the workflow goes, let’s assume Jean wants to fix a bug in the code. Here are the steps:

1. Jean creates a separate branch in her local repo and fixes the bug in that branch.
2. Jean pushes the branch to her fork.
3. Jean creates a pull request from that branch in her fork to the main repo.
4. Other members review Jean’s pull request.
5. If reviewers suggested any changes, Jean updates the PR accordingly.
6. When reviewers are satisfied with the PR, one of the members (usually the team lead or a designated 'maintainer' of the main repo) merges the PR, which brings Jean’s code to the main repo.
7. Other members, realizing there is new code in the upstream repo, sync their forks with the new upstream repo (i.e. the main repo). This is done by pulling the new code to their own local repo and pushing the updated code to their own fork.

• A detailed explanation of the Forking Workflow - From Atlassian

4. One member: create a PR from your team repo master branch to [nus-cs2103-AY1718S2/addressbook-level4] master branch. PR name: [v1.x][Team ID] Product Name e.g., [v1.x][T09-B2] Contact List Pro.  As you merge code to your team repo's master branch, this PR will auto-update to reflect how much your team's product has progressed (that's why we use v1.x instead of v1.0 in the PR title). In the PR description mention the other team members so that they get notified when the tutor adds comments to the PR.

v1.0 Product

Objective: To familiarize yourself with at least one component the code.

Description: Divide the components among yourselves. Each member can do some small enhancements to their component(s) to learn the code of that component. Some suggested enhancements are given in the AddressBook-Level4 developer guide.

❗️ Before you start coding, please read our reuse policy given below, in particular, how to give credit when you reuse code from Internet or classmates:

Submission: Create PRs from your own fork to your team repo. Get it merged by following your team's workflow.

v1.1 Product

[An early version of the mobile phone]

Objective: Move the product from v1.0 towards v2.0 in a small incremental step.

Description:

• Each member should add some enhancements that are in line with the vision for v2.0. We recommend this to be your minor enhancement, but it can also be an initial step in your major enhancement.

• These enhancements should go beyond the component you are in charge of, touching as many other components as possible. Refer to the AddressBook-Level4 Developer Guide has some guidance on how to implement a new feature end-to-end.

Submission: Demo of the new functionality during the tutorial.

v1.1 Documentation

Update the following pages:

• User Guide:
  Update the user guide to describe what the product would be like when it is at 2.0. Mark features not implemented yet as Coming in v2.0. You may use UI mockups where necessary.

• About Us page:
  This page is used for module admin purposes. Please follow the format closely to avoid penalties.
  • Replace info of SE-EDU developers with info of your team, including a suitable photo as described here.
  • Including the name/photo of the supervisor/lecturer is optional.
  • The photo of a team member should be doc/images/githbub_username_in_lower_case.png e.g. docs/images/damithc.png.

• Indicate the different roles played and responsibilities held by each team member. You can reassign these roles and responsibilities later in the project, if necessary.

• README.adoc page: Update it to match your project.
  • Add a UI mockup of your intended final product.
    Note that the image of the UI should be docs/images/Ui.png so that it can be downloaded by our scripts.
  • The original README.adoc file (which doubles as the landing page of your project website) is written to read like the introduction to an SE learning/teaching resource. You should restructure this page to look like the home page of a real product (not a school project) targeting real users  e.g. remove references to addressbook-level3, Learning Outcomes etc. mention target users, add a marketing blurb etc. On a related note, also remove Learning Outcomes link and related pages.
  • Acknowledge the original source of the code i.e. AddressBook-Level4 project created by SE-EDU initiative at https://github.com/se-edu/

Preparation:

• Ensure you have access to a computer that is able to run module projects  e.g. has the right Java version.
• Have a good screen grab tool with annotation features so that you can quickly take a screenshot of a bug, annotate it, and post in the issue tracker.
• 💡 You can use Ctrl+V to paste a picture from the clipboard into a text box in GitHub issue tracker.

• Duration: Strictly (teamSize x 3) + 1 minutes  e.g. 13 minutes for a 4-person team. Exceeding this limit will be penalized. The extra minute is for the first speaker to give an overview of the product.

• Target audience: Assume you are giving a demo to a higher-level manager of your company, to brief him/her on the current capabilities of the product. This is the first time they are seeing the new product you developed but they are familiar with the AddressBook-level4 (AB4) product.

• Scope:

  • Each person should demo the enhancements they added. However, it's ok for one member to do all the typing.
  • Subjected to the constraint mentioned in the previous point, as far as possible, organize the demo to present a cohesive picture of the product as a whole, presented in a logical order.  Remember to explain the profile of the target user profile and value proposition early in the demo.
  • It is recommended you showcase how the feature improves the user’s life rather than simply describe each feature.
  • No need to cover design/implementation details as the manager is not interested in those details.
  • Mention features you inherited from AB4 only if they are needed to explain your new features.  Reason: existing features will not earn you marks, and the audience is already familiar with AB4 features.

• Structure:

  • Demo the product using the same executable you submitted, on your own laptop, using the TV.
  • It can be a sitting down demo: You'll be demonstrating the features using the TV while sitting down. But you may stand around the TV if you prefer that way.
  • It will be uninterrupted demo: The audience members will not interrupt you during the demo. That means you should finish within the given time.
  • The app should be populated with a significant amount of realistic data at the start.  e.g at least 20 contacts.
  • Dress code : The level of formality is up to you, but it is recommended that the whole team dress at the same level.

• Optimizing the time:

  • Spend as much time as possible on demonstrating the actual product. Not recommended to use slides (if you do, use them sparingly) or videos or lengthy narrations.
    Avoid skits, re-enactments, dramatizations etc. This is not a sales pitch or an informercial. While you need to show how a user use the product to get value, but you don’t need to act like an imaginary user. For example, [Instead of this]Jim get’s a call from boss. "Ring ring", "hello", "oh hi Jim, can we postpone the meeting?" "Sure". Jim hang up and curses the boss under his breath. Now he starts typing ..etc. [do this] If Jim needs to postpone the meeting, he can type …
    It’s not that dramatization is bad or we don’t like it. We simply don’t have enough time for it.
    Note that CS2101 demo requirements may differ. Different context → Different requirements.
  • Rehearse the steps well and ensure you can do a smooth demo. Poor quality demos can affect your grade.
  • Don’t waste time repeating things the target audience already knows. e.g. no need to say things like "We are students from NUS, SoC".
  • Bring sufficient amount of sample data and know how to load them to the system. You should not plan to type all the sample data during the demo itself. On the other hand, trying to demo a product using just 1-2 sample data creates a bad impression too.
  • Plan the demo to be in sync with the impression you want to create. For example, if you are trying to convince that the product is easy to use, show the easiest way to perform a task before you show the full command with all the bells and whistles.
  • Limit the demo to CLI inputs only. There is no point explaining GUI inputs because they don't earn marks.

v1.5 Practical Exam

Objectives:

• Evaluate your,
  • manual testing skills
  • product evaluation skills
  • effort estimation skills
• Peer-evaluate your
  • product design 👥
  • implementation effort 👤
  • documentation quality 👤

Time/venue: week 13 lecture slot, lecture theatre

During:

1. **Take note of your team to test **. Team ID will be given to you by the teaching team (distributed via IVLE gradebook).
2. Download from IVLE all files submitted by the team  (i.e. jar file, User Guide, Developer Guide, and Project Portfolio Pages) into an empty folder.
3. [~40 minutes] Test the product and report bugs
   • Launch the jar file. Test it.
   • You can use Developer Guide (Appendix named Instructions for Manual Testing) and the User Guide in your testing.
   • No need to test features that are driven by GUI inputs (e.g. buttons, menus, etc.)  Reason: Only CLI-driven features can earn credit, as per given project constraints. Some features might have both a GUI-driven and CLI-driven ways to invoke them, in which case test only the CLI-driven way of invoking it.
   • The testing instructions in the Developer Guide can provide you some guidance but if you follow those instructions strictly, you are unlikely to find many bugs. You can deviate from the instructions to probe areas that are more likely to have bugs.
   • You can do acceptance testing as well as system testing.
   • Omit feature that existed in AB4. Instead, test features the team has added.
   • Report bugs in the [practical exam issue tracker](URL will be given) not in the team's repo.
     • Issue title format: [Team ID] Issue description  e.g. [561] Empty name crashes app
   • Report bugs only. Do not post suggestions. These are considered bugs:
     • Behavior differs from the User Guide (or Developer Guide)
     • A legitimate user behavior is not handled  e.g. incorrect commands, extra parameters
     • Behavior is not specified and differs from normal expectations  e.g. error message does not match the error
   • Write good quality bug reports; ❗️ poor quality or incorrect bug reports will not earn credit.
     • Use a descriptive title
     • Give a good description of the bug with steps to reproduce and screenshots
     • 🔍 Note that we will anonymize bug reports before revealing it to the receiving team.
   • Assign a severity to the bug report:

1. [~40 minutes] Evaluate the following aspects. Note down your evaluation in a hard copy (as a backup). Submit via TEAMMATES.

   • A. Cohesiveness of product features [👥]: Do the major features fit together and match the stated target user and the value proposition?

     • low: One of these
       • target user is too general  i.e. not narrower than AB4
       • target user and value proposition is not clear from the user guide OR
       • features don't seem to match for the most part
     • medium: Some features match but some don't
     • high: all features match but the features are not very high value to the target user
     • excellent: the product is very attractive to the target user. i.e. and almost all new features are of high-value to the target user.
     • unable to judge: you are unable to judge this aspect for some reason

   • B. Quality of user docs [👤]: Evaluate based on the parts of the user guide written by the person, as reproduced in the project portfolio. Evaluate from an end-user perspective.

     • low: Hard to understand, often inaccurate or missing important information
     • medium:
     • high: Mostly easy to follow. Only a few areas for improvements.
     • excellent: Easy to follow and accurate. Just enough information, visuals, examples etc. (not too much either).
     • unable to judge: less than 1 page worth of UG content written by the student

   • C. Amount of work [👤]: Evaluate the amount of work on a scale of 0 to 30

     • Consider this PR (history command) as 5 units of effort which means this PR (undo/redo command) is about 15 points of effort. Given that 30 points matches an effort twice as that needed for the undo/redo feature (which was given as an example of an A grade project), we expect most students to be have efforts lower than 20.
     • Count all implementation/testing/documentation work as mentioned in that person's portfolio page.
     • ❗️ Do not give a high value just to be nice. If your estimate is wildly inaccurate, it means you are unable to estimate the effort required to implement a feature in a project that you are supposed to know well at this point. You will lose marks if that is the case.
     • When estimating effort, ignore features that are driven by GUI inputs.

   • D. Depth of feature (major feature) [👤]: Evaluate the major feature done by the student for difficulty, depth, and completeness. Note: examples given below assumes AB4 did not have commandsedit undo redo

     • low : an easy feature  e.g. make the existing find command case insensitive
     • medium : moderately difficult feature, barely acceptable implementation  e.g. an edit command that requires the user to type all fields, even the ones that are not being edited
     • high: one of the below
       • A moderately difficult feature but fully implemented  e.g. an edit command that allows editing any field
       • A difficult feature with a reasonable implementation but some aspects are not covered  undo/redo command that only allows a single undo/redo
     • excellent: A difficult feature, all reasonable aspects are fully implemented  undo/redo command that allows multiple undo/redo
     • outstanding: A difficult feature, implemented as good as it can be under the circumstances.  undo/redo command that even allows undoing non-mutating commands such as select, allows selectively undo specific commands in the history, etc.
     • unable to judge: you are unable to judge this aspect for some reason

   • E. Quality of developer docs [👤]: Evaluate based on the developer docs cited/reproduced in the respective project portfolio page. Evaluate from the perspective of a new developer trying to understand how the features are implemented.

     • low: One of these
       • Very small amount of content (i.e., 0.5 - 1 page)
       • Hardly any use to the reader (i.e., content doesn't make much sense or redundant)
       • Uses ad-hoc diagrams where UML diagrams could have been used instead
       • Multiple notation errors in UML diagrams
     • medium: Some diagrams, some descriptions, but does not help the reader that much  e.g. overly complicated diagrams
     • high: Enough diagrams (at lest two kinds of UML diagrams used) and enough descriptions (about 2 pages worth) but explanations are not always easy to follow.
     • excellent: Easy to follow. Just enough information (not too much). Minimum repetition of content/diagrams. Good use of diagrams to complement text descriptions. Easy to understand diagrams with just enough details rather than very complicated diagrams that are hard to understand.
     • unable to judge: One of these
       • no content at all
       • less than 0.5 pages worth of content
       • other problems in the document  e.g. looks like included wrong content

Bug Review Period:

There will be a review period for you to respond to the [bug reports](URL will be given) you received.

Duration: The review period will start around 1 day after the PE (exact time to be announced) and will last until the following Wednesday midnight.

Bug reviewing is recommended to be done as a team as some of the decisions need team consensus.

Grading:

• Your performance in the practical exam will be considered for your final grade (under the QA category and under Implementation category, about 10 marks in total).
• You will be graded based on many bugs in the product you tested and how far off your evaluation/estimates are from the evaluator consensus.  Explanation: we understand that you have limited expertise in this area; hence, we penalize only if your inputs don't seem be be based on a sincere effort to test/evaluate.
• The bugs found in your product by others will affect your v1.5 marks. You will be given a chance to reject false-positive bug reports.

Communication: Keeping a record of communications among your team can help you, and us, in many ways. We encourage you to do at least some of the project communication in written medium (e.g., GitHub Issue Tracker) to practice how to communicate technical things in written form.

• Instead of the IVLE forum, we encourage you to post your questions/suggestions in this github/nus-cs2103-AY1718S2/forum.
• Alternatively, you can post in our slack channel https://nus-cs2103-ay1718s2.slack.com. We encourage you all to join the slack channel (you'll need to use an email address ending in @nus.edu.sg, @comp.nus.edu.sg, @u.nus.edu.sg or @u.nus.edu to join this channel).
• Note that slack is useful for quick chats while issue tracker is useful for longer-running conversations.
• You are encouraged to use channels with a wider audience (common channel in slack, GitHub issue tracker) for module-related communication as much as possible, rather than private channels such as private slack/FB messages or direct emails. Rationale: more classmates can benefit from the discussions.

When working with others, especially in a large class such as CS2103,  it is very important that you adhere to standards, policies, and instructions imposed on everyone. Not doing so creates unnecessary headaches for everyone and puts your work attitude in a negative light. That is why we penalize repeated violations of instructions. On the other hand we do understand that humans are liable to make mistakes. That is why we only penalize repeated or frequent mistakes.

As most of the work is graded individually, team sizes of 3, 4, or 5 is not expected to affect your grade. While managing larger teams is harder, larger teams have more collective know-how, which can cancel each other.

As most of the work is graded individually, it is OK to do less or more than equal share in your project team.

There is no need to inform us. If you miss a lecture/tutorial for a valid reason, just do your best to catch up. We'll be happy to help if required. An occasional absence or two is not expected to affect your participation marks. 
Only if you fail to earn full marks for participation we will consider giving an alternative avenue to earn marks missed due to the absences.

Normally, the prof will respond within 24 hours if it was an email sent to the prof or a forum post directed at the prof. If you don't get a response within that time, please feel free to remind the prof. It is likely that the prof did not notice your post or the email got stuck somewhere.

Similarly we expect you to check email regularly and respond to emails written to you personally (not mass email) promptly.

Do not expect your project tutor to code or debug for you. We strongly discourage tutors from giving technical help directly to their own teams because we want to train you in troubleshooting tech problems yourselves. Allowing direct tech help from tutors transfers the troubleshooting responsibility to tutors.

It is ok to ask for help from classmates even for assignments, even from other teams, as long as you don't copy from others and submit as your own. It doesn't matter who is helping you as long as you are learning from it.

We encourage you to give tech help to each other, but do it in a way that the other person learns from it.

We want to move you away from 'hand holding' and make you learn how to solve problems on your own. This is a vital survival skill in the industry and it needs practice.

Whether it is a technical problem (e.g. error when using the IDE) or a doubt about a concept (e.g. what is the difference between scripted testing and exploratory testing?)  we the teaching team are happy to work with you when you look for a solution/answer, but we do not do it for you. We discourage unconditional direct help from tutors because we want you to learn to help yourself. Yes, we believe in ‘tough love’😝.

The question you should always ask yourself is, 'how do I solve this problem if the lecturer/tutors are not around to help me?'

Note: This guide is mostly about getting tech help, but it also applies to getting clarifications on module topics too. e.g. what is the difference between refactoring and rewriting?

What not to do:

When faced with a technical problem or a doubt about a concept, don'f fire off an email lecturer/tutor immediately after you encounter a problem or a doubt, unless it is something only the lecturer/tutor is supposed to know. Instead, here are some things you can do:

• Check what is given: Check if the problem/concept has been discussed in the lectures, text book, or the list of resources given to you. Yes it is easier for you to write an email to the tutor/lecturer instead, but that shouldn't be your default behavior. We know that sometimes it is difficult to find stuff in the resources we have provided. But you should try first.

• Search: It is very likely the answer already exists somewhere in the cyberspace. Almost every programming-related question has been answered in places like stackoverflow. Don't give an opportunity for someone to ask you to STFW.
  Pay attention to the error message you encounter. Sometimes it also contains hints as to how to fix the problem. Even if not, a web search on the error message is a good starting point.  
  

• Ask peers:

  Ask your team members.

  Ask classmates using the module forum or the slack channel. Even if you figured out one way to solve a problem, discussing it on a public forum might lead you to better ways of solving it, and will help other classmates who are facing similar problems too. If you are really shy to ask questions in the forum, you may use this form to submit your question anonymously which we will then post in the forum.

  
  

  Rubber duck debugging is an informal term used in software engineering to refer to a method of debugging code. The name is a reference to a story in the book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug his code by forcing himself to explain it, line-by-line, to the duck.

  [for more, see wikipedia entry]

• Ask the world using programming forums such as stackoverflow.

  Here are some tips for posting help request:

  • PLEASE search for existing answers before you post your question in those public forums; You don't want to appear as a 'clueless' or 'too lazy to do your research' person in a public forum.

  • Learn to isolate the problem. "My code doesn't work" isn't going to help even if you post the whole code online. Others don't have time to go through all of your code. Isolate the part that doesn't work and strip it down to the bare minimum that is enough reproduce the error. Sometimes, this process actually helps you to figure out the problem yourself. If not, at least it increases the chance of someone else being able to help you.

    💡 How to isolate problematic code? Delete code (one bit at a time) that is confirmed as not related to the problem. Do that until you can still reproduce the problem with the least amount of code remaining.

  • Generalize the problem. "How to write tasks to a text file using Java" is too specific to what you are working on. You are more likely to find help if you post a thread called (or search for) "How to write to a file using Java".

  • Explain well. Conversations via online forums take time. If you post everything that is relevant to your problem, your chances of getting an answer in the first try is higher. If others have to ask you more questions before they can help you, it will take longer. But this doesn't mean you dump too much information into the thread either.

    💡 Know what these stand for: RTFM, STFW, GIYF

• Talk to the lecturer before or after the lecture. The lecturer will be at the lecture venue from 30 minutes before the start of the lecture.

• Request our help: Failing all above, you can always request for help by emailing the lecturer.

Resources

• [lifehacker article]  Google Tips and Tricks Every Student Should Know
• [Article] How To Ask Questions The Smart Way by Eric Steven Raymond

The source code are publicly available and are available for reuse by others without any restrictions. 
Is publishing submissions unfair to the team? We don't think so. If you were the first to think of something your peers are willing to adopt later, that means you are already ahead of them and they are unlikely to earn more marks by adopting your ideas.

We encourage sharing, but you should share with everyone in the class, not just a selected group. That is,

• You are not allowed to share individual assignments with classmates directly.
• You are not allowed to share project-related things with other teams directly.

You can even reuse each other's work subject to the 'reuse policy' given below.

If you submit code (or adopt ideas) taken from elsewhere, you need to comply with our reuse policy.

Detection:

• Detecting plagiarism in code is quite easy. You are not fooling anyone by reordering code or renaming methods/variables.
• As all your work is publicly visible on GitHub, sooner or later somebody will notice the plagiarism.

Penalties:

• For submissions not affecting marks: We make a record of cases of plagiarism but we do not take further action. Such plagiarism does not disadvantage other students. Therefore, we prefer to spend all available resources on helping honest students to do better rather than to chase after dishonest students. If you think you gain something by plagiarizing, go ahead and do it. It's your choice and it's your loss.
• For the final project/exam: Any case of claiming others' work as yours will be reported to the university for disciplinary action.

In general, you are not allowed to involve outsiders in your project except your team members and the teaching team. However, It is OK to give your product to others for the purpose of getting voluntary user feedback. It is also OK to learn from others as long as they don't do your project work themselves.

We don't usually give a strict page limit for documents such as User Guide and the Developer Guide. You need to decide yourself how long the document should be based on the purpose and the intended audience. You can determine the level of details required based on the samples we provide.

The Schedule page is the one page you need to refer weekly. Although there is a lot of content in the Admin page and the Textbook page -- which you are welcome to read in those respective pages -- the same content is also embedded in the relevant weeks of the Schedule page. In sum, the Schedule page organizes the content chronologically while the other two pages has some of the same content but organized by topic.

Same lectures, same exam. Separate tutorials, separate project grading. Unless specified otherwise, whatever is stated for one module applies to the other.

CS2103/T prepares you for many higher-level project modules (CS3216/7, CS3201/2, CS3281/2, CG3002, etc.), each requiring a slightly different skill set. It is also the only SE course some of you do before going for industry internships. Therefore, we have to cover many essential SE concepts/skills and also provide enough exercises for you to practice those skills. This is also why we don't have time to go very deep into any of the topics.

Remember, everything you learn here is going to be useful in a SE-related career.

Also, consider this a gradual introduction to 'heavy' modules; most project modules you do after this are going to be much heavier 😛

How to reduce the workload? You can omit Learning Outcomes rated ⭐️⭐️⭐️⭐️ They are counted for CS2103R and for A+ grades only.

General info on R modules are here.

To get CS2103R credit you should,

• Achieve most of the 3-⭐️ LOs and some of the 4-⭐️ LOs during the semester.
• Inform prof your interest to do CS2103 at the end of the semester.
• Achieve the missed 3-⭐️ and 4-⭐️ LOs during the vacation.
• Register for CS2103R in the subsequent semester.

In CS2103/T, A+ is not given simply based on the final score. To get an A+ you should,

• score enough to get an A
• be considered technically competent by peers and tutor (based on peer evaluations and tutor observations)
• be considered helpful by peers (based on peer evaluations and tutor observations)
  • In particular, you are encouraged to be active on the slack channel and our forum and give your inputs to ongoing discussions so that other students can benefit from your relatively higher expertise that makes you deserve an A+.
  • Whenever you can, go out of your way to review PRs created by other class members (as part of weekly LOs), even if they are not in your team.
• achieve most of the 3-⭐️ LOs and some of the 4-⭐️ LOs.

Sometimes, small things matter in big ways. e.g., all other things being equal, a job may be offered to the candidate who has the neater looking CV although both have the same qualifications. This may be unfair, but that's how the world works. Students forget this harsh reality when they are in the protected environment of the school and tend to get sloppy with their work habits. That is why we reward all positive behavior, even small ones (e.g., following precise submission instructions, arriving on time etc.).

But unlike the real world, we are forgiving. That is why you can still earn full 10 marks of the participation marks even if you miss a few things here and there.

Related article: This Is The Personality Trait That Most Often Predicts Success (this is why we reward things like punctuality).

We have a separate website because some of the module information does not fit into the structure imposed by IVLE.

On a related note, keep in mind that 'hunting and gathering' of relevant information is one of the skills you need to survive 'in the wild'. Do not always expect all relevant materials to appear 'magically' in some kind of 'work bin'.

Slides are not meant to be documents to print and study for exams. Their purpose is to support the lecture delivery and keep you engaged during the lecture. That's why our slides are less detailed and more visual.

Self-study is a critical survival skill in SE industry. Lectures will show you the way, but absorbing content is to be done at your own pace, by yourself. In this module, we still tell you what content to study and also pass most of the content to you. After you graduate, you have to decide what to study and find your own content too.

If you do not have a laptop or prefer not to bring the laptop, it is up to you to show your work to the tutor in some way (e.g. by connecting to your home PC remotely), without requiring extra time/effort from the tutor or team members.

Reason: As you enjoy the benefits of not bring the laptop; you (not others) should bear the cost too.

Defining your own unique project is more fun.

But, wider scope → more diverse projects → harder for us to go deep into your project. The collective know-how we (i.e., students and the teaching team) have built up about SE issues related to the project become shallow and stretched too thinly. It also affects fairness of grading.

That is why a strictly-defined project is more suitable for a first course in SE that focuses on nuts-and-bolts of SE. After learning those fundamentals, in higher level project modules you can focus more on the creative side of software projects without being dragged down by nuts-and-bolts SE issues (because you already know how to deal with them). However, we would like to allow some room for creativity too. That is why we let you build products that are slight variations of a given theme.

Also note: The freedom to do 'anything' is not a necessary condition for creativity. Do not mistake being different for being creative. In fact, the more constrained you are, the more you need creativity to stand out.

"You tell me exactly what to do - I do that - you pay me (in grades)" is a model for contract work, not for learning. Being able to survive in imprecise, uncertain, volatile problem contexts is precisely what we are trying to teach you.

For example, the best way to communicate something often depends on what is being communicated. That is why we don't specify the precise content for project documents. Instead, we aim to refine project documents iteratively. We believe the learning experience will be richer if we let you decide the best way to present your project information rather than just following our instructions blindly. For example, in real-life projects you are rarely told which diagrams to draw; that is a decision you have to make yourself.

We have chosen a basic set of tools after considering ease of learning, availability, typical-ness, popularity, migration path to other tools, etc. There are many reasons for limiting your choices:

Pedagogical reasons:

• Sometimes 'good enough', not necessarily the best, tools are a better fit for beginners: Most bleeding edge, most specialized, or most sophisticated tools are not suitable for a beginner course. After mastering our toolset, you will find it easy to upgrade to such high-end tools by yourself. We do expect you to eventually (after this module) migrate to better tools and, having learned more than one tool, to attain a more general understanding about a family of tools.
• We want you to learn to thrive under given conditions: As a professional Software Engineer, you must learn to be productive in any given tool environment, rather than insist on using your preferred tools. It is usually in small companies doing less important work that you get to chose your own toolset. Bigger companies working on mature products often impose some choices on developers, such as the project management tool, code repository, IDE, language etc. For example, Google used SVN as their revision control software until very recently, long after SVN fell out of popularity among developers. Sometimes this is due to cost reasons (tool licensing cost), and sometimes due to legacy reasons (because the tool is already entrenched in their code base).
  While programming in school is often a solo sport, programming in the industry is a team sport. As we are training you to become professional software engineers, it is important to get over the psychological hurdle of needing to satisfy individual preferences and get used to making the best of a given environment.

Practical reasons:

• Some of the LOs are tightly coupled to tools. Allowing more tools means tutors need to learn more tools, which increases their workload.
• We provide learning resources for tools. e.g. 'Git guides'. Allowing more tools means we need to produce more resources.
• When all students use the same tool, the collective expertise of the tool is more, increasing the opportunities for you to learn from each others.

Meanwhile, feel free to share with peers your experience of using other tools.

The high number of submissions is not meant to increase workload but to spread it across the semester. Learning theory and applying them should be done in parallel to maximize the learning effect. That can happen only if we spread theory and 'application of theory' (i.e., project work) evenly across the semester.

There are many reasons. One of them is that most of you will be working with existing software in your first few years of the career while hardly any school projects train you to work with existing code bases. We decided to bite the bullet and use CS2103/T to train you to work in existing code bases.

They do, and they should.

CS2103T communication requirements are limited to a very narrow scope (i.e., communicate about the product to users and developers). CS2101 aims to teach you technical communication in a much wider context. While you may be able to reuse some of the stuff across the two modules, submissions are not intended to be exactly the same.

Create a personal GitHub account if you don't have one yet.

1. You are advised to choose a sensible GitHub username as you are likely to use it for years to come in professional contexts.
2. Strongly recommended: Complete your GitHub profile. In particular,
   • Specify your full name.
   • Upload a suitable profile photo (i.e. a recent photo of your face).

Setting Git Username to Match GitHub Username

We use various tools to analyze your code. For us to be able to identify your commits, you should use the GitHub username as your Git username as well. If there is a mismatch, or if you use multiple user names for Git, our tools might miss some of your work and as a result you might not get credit for some of your work.

In each Computer you use for coding, after installing Git, you should set the Git username as follows.

1. Open a command window that can run Git commands (e.g., Git bash window)
2. Run the command git config --global user.name YOUR_GITHUB_USERNAME
   e.g., git config --global user.name JohnDoe
   ( Note: if you are using git for other projects, you may want to remove the --global flag and run the command only for cs2103 related repos)

More info about setting Git username is here.

Submitting Pull Requests as evidence of an LO

1. Fork the repo to your personal GitHub account, if you haven't done so already.

2. Create a branch named after the LO IDe.g. W2.2b
   Remember to switch to master branch before creating the new branch.

3. Commit your changes to that branch. Push to your fork.

4. Create a Pull Request against the master branch of the repo
   https://github.com/nus-cs2103-AY1718S2/{repo_name}
   e.g. https://github.com/nus-cs2103-AY1718S2/addressbook-level1
   (do not create PRs against the upstream repo at se-edu org)
   
   PR name should be: [LO_ID][TEAM_ID]Your Name
   e.g. If you are in team 1 of tutorial W09 (i.e. Wednesday 9am), [W2.2b][W09-A1]James Yong. Your Team ID can be found in this page. Note that our tutorial IDs are different from those shown in CORS/IVLE. Our tutorial IDs are given in the panel below.

5. Check the 'Files Changed' tab on GitHub to confirm the PR contains intended changes only.
   

6. If the content of the PR is not as you expected, you can fix those problems in your local repo, commit, and push those new commits to the fork. The PR content will update automatically to match new commits. Alternatively, you can close that PR and create a new one with the correct content.

7. If your PR adapted/referred code from elsewhere (e.g. a stackoverflow post or a classmate's PR -- which is allowed, even encouraged), acknowledge the source in your PR description text. e.g. Some code adapted from #2431 (I followed the same technique for parsing user command)

8. If the PR is not ready for review yet, add a comment Work in progress. When the PR is ready for review later, add a comment Ready for review If there is no comment, we assume the PR is ready for review.

Organization setup

The instructions below are for setting up a GitHub organization for your team, which you should do at the start of Phase B.

You can create your GitHub account after receiving your Phase B team ID. Here are the instructions (please follow the organization/repo name format closely because we use scripts to download your code. If the names are not as expected, our scripts will not work):

• One team member (e.g. team leader) should create an organization with the following details:
• Organization name : CS2103JAN2018-TEAM_ID. e.g.  CS2103JAN2018-W09-B3
• Plan:  Open Source ($0/month)
• After that, the same person can add members to the organization:
• Create a team called developers to your organization.
• Add your team members to the developers team.

Repo setup

Only one team member:

1. Fork Address Book Level 4 to your team org.
2. Rename the forked repo as main. This repo is to be used as the repo for your project.
3. Ensure your team members have the desired level of access to your team repo

All team members:

1. Fork the main repo (created above) to your personal GitHub account.
2. Clone the fork to your Computer.
3. Set it up as an Intellij project (follow the instructions in the Developer Guide carefully).

Note that some of our download scripts depend on the following folder paths. Please do not alter those paths in your project.

• /src/main
• /src/test
• /docs

Issue tracker setup

When you create a repo, you get an issue tracker for that repo automatically. Configure it as follows:

• Delete existing labels and add the following labels.

• Create following milestones : v1.0, v1.1, v1.2, v1.3, v1.4, v1.5rc, v1.5

• You may configure other project settings as you wish. e.g. more labels, more milestones

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 new 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. Title: As a user I can add a deadline
Description: ... so that I can keep track of my deadlines

• Assign the type.* and priority.* labels to those issues.

• When you start implementing a story, break it down to tasks. Define reasonable sized, standalone tasks. A task should be able to done by one person, in a few hours. e.g.

  • 👍 Good: Update class diagram in the project manual for v1.5
  • 👎 Bad (reasons: not a one-person task, not small enough): Write the project manual

• Write a descriptive title for the issue. e.g. Add support for the 'undo' command to the parser.

• 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.,

  • Implementing parser  : too big because it cannot be done by a single person in a week.
  • Implementing parser support for adding of floating tasks : appropriate size.

• 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.

• Omit redundant details. In some cases, the summary/title is enough to describe the task. In that case, no need to repeat it in the 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 to team members using the assignees field. At any point, there should be some ongoing tasks and some pending tasks against each team member.

• Optionally, you can use status.ongoing label to indicate issues currently ongoing.

Workflow

We recommend using the Forking Workflow.