Project Setup

Create your team organization.

Set up the team repo

Setup the issue tracker in the team repo

Port the phase 1 code to your team repo

• Now carefully port the phase 1 code to the team repo you setup above.
• (Caution!) This can be messy.
  • You are allowed to decide and choose which team member's code goes into the team repo. There can be various combinations.
    • E.g., Codebase for different purposes (interaction, storage to file, logic, etc.,) can belong to different team members.
    • E.g., Entire codebase from Phase 1 can belong to just one or two team members.
  • However, the decision on whose code is used should be made collectively within the team, the teaching team will not intervene.
  • In the interest of the team, you can choose the best code to be the starter codebase.
  • Note: You will be graded individually for your Phase 1 of the project, so irrespective of your code being used or not used as the base code for the team project, you will have received the due credit for your work. Conversely, since your work is evaluated in Phase 1, you will not receive any additional credits if your code is used as the base code for the team project.
• Push the changes to the team repo.

Organization setup

Please follow the organization/repo name format precisely because we use scripts to download your code or else our scripts will not be able to detect your work.

After receiving your team ID, one team member should do the following steps:

• Create a GitHub organization with the following details:
  • Organization name : SEMESTER-TEAM_ID. e.g.  AY1920S1-CS2113T-W12-2 or AY1920S1-CS2113-T13-1
  • Plan:  Open Source ($0/month)
• 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 nuscs2113-AY1920S1/PersonalAssistant-Duke to your team org.
2. Rename the forked repo as main. This repo (let's call it the team repo) is to be used as the repo for your project.
3. Ensure the issue tracker of your team repo is enabled. Reason: our bots will be posting your weekly progress reports on the issue tracker of your team repo.
4. Ensure your team members have the desired level of access to your team repo.
5. create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nuscs2113-AY1920S1/PersonalAssistant-Duke] master branch. PR name: [Team ID] Product Name e.g., [AY1920S1-CS2113-T13-1] 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. In the PR description @mention the other team members so that they get notified when the tutor adds comments to the PR.

All team members:

1. Watchthe main repo (created above) i.e., go to the repo and click on the watch button to subscribe to activities of the repo
2. Fork the main repo to your personal GitHub account.
3. Clone the fork to your Computer.
4. Recommended: Set it up as an Intellij project.

Note that some of our download scripts depend on the following folder paths. Please set up the these paths in your project carefully.

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

Issue tracker setup

We recommend you configure the issue tracker of the main 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.

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

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

A. Process:

Evaluates: How well you did in project management related aspects of the project, as an individual and as a team

Based on: Supervisor observations of project milestones and GitHub data.

Milestones need to be reached the midnight before of the tutorial for it to be counted as achieved. To get a good grade for this aspect, achieve at least 60% of the recommended milestone progress.

Other criteria:

• Good use of GitHub milestones
• Good use of GitHub release mechanism
• Good version control, based on the repo
• Reasonable attempt to use the forking workflow
• Good task definition, assignment and tracking, based on the issue tracker
• Good use of buffers (opposite: everything at the last minute)
• Project done iteratively and incrementally (opposite: doing most of the work in one big burst)

B. Team-tasks:

Evaluates: How much did you contribute to team-tasks?

Based on: peer evaluations and tutor observations

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

1. 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
2. Setting up the GitHub, Travis, AppVeyor, etc.
3. Maintaining the issue tracker
4. Release management
5. Updating user/developer docs that are not specific to a feature e.g. documenting the target user profile
6. 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)

• The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly (i.e., not too small) -- somewhat similar to a passport photo. Some examples can be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.
  

• If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.

Documentation:

• User Guide:
  Start drafting a user guide in a convenient medium (e.g., a GoogleDoc) to describe what the product would be like when it is at v2.0. Which means, you can include commands that you may not implement in the project.

  • We recommend that you follow the reference project's User Guide in terms of structure and format.
  • As this is a beginning draft, don't waste time in formatting, copy editing, etc. It is fine as long as the tutor can get a rough idea of the features from this draft. You can also do just the 'Features' section and omit the other parts.
  • However, do try to come up with concrete command syntax for feature that you would implement (at least for those that you will implement by v1.4).
  • Include a mock-up of how your interface may look (e.g., either GUI or CLI landing screen). (GUI mock-up can be hand-drawn or created using a tool such as PowerPoint or Balsamiq).

• Developer Guide:
  Update the developer guide (target user profile, user stories, use cases, and non-functional requirements) based on the feedback from your tutors.

Admin pages:

• Create the About Us page:
  Use this page from the reference project as a reference for the format. We need this page for module admin purposes. Please follow the format closely or else our scripts will not be able to give credit for your work.
  • You may copy the page and 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 docs/images/githbub_username_in_lower_case.png e.g. docs/images/johndoe.png. If you photo is in jpg format, name the file as .png anyway.
  • Indicate the different roles played and responsibilities held by each team member. You can reassign these roles and responsibilities (as explained in Admin Project Scope) later in the project, if necessary.

• README page: Update it to match your project.

  • Add a UI mock-up 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. Limit the file to contain one screenshot/mock-up only and ensure the new image is roughly 1280px X 1024px in size. Reason: when we compile these images from all teams into one page (example), yours should not look out of place.

  • The original README file (which doubles as the landing page of your project website) is written to read like a setup instructions page. 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 the section on feedback and reference to duke issue tracker

• The purpose of the profile photo is for the teaching team to identify you. Therefore, you should choose a recent individual photo showing your face clearly (i.e., not too small) -- somewhat similar to a passport photo. Some examples can be seen in the 'Teaching team' page. Given below are some examples of good and bad profile photos.
  

• If you are uncomfortable posting your photo due to security reasons, you can post a lower resolution image so that it is hard for someone to misuse that image for fraudulent purposes. If you are concerned about privacy, you can request permission to omit your photo from the page by writing to prof.

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

  Recommended roles and responsibilities

  Recommended roles and responsibilities

Please make sure 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.

Project Phase 2

• Step 0 : Identify the target user profile and the problem you are solving for the target users

  Decide on the project direction (e.g., enhance or morph?)
  Document these details in the introduction section of your developer guide.

• Step 1 : Brainstorm user stories

  

  This is a good time to analyze requirements with a view to conceptualizing the next version of the product (i.e. v2.0).

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

• Step 2: 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 3: Document requirements of the product

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

    Document the following items using a convenient format (e.g., a GoogleDoc).

    • Target user profile, value proposition, and user stories: Update the target user profile and value proposition to match the project direction you have selected. Record the list of the user stories, including priorities in the correct format (It is suggested to use a tabular format similar to the examples shown in the lecture). 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 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).

Requirements → Gathering Requirements →

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.

User stories in use

User stories in use

With sticky notes

With sticky notes

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

---

With paper

With paper

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

---

With software

With software

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

---

---

Exercises

Exercises

Given their lightweight nature, user stories are quite handy for recording requirements during early stages of requirements gathering.