Week 7 [Mon, Sep 30th] - Project

iP:

  1. [Optional] Get more out of the iP

tP: v1.1

  1. Do a 'workflow practice' session Thu, Oct 3rd 23:59
  2. Update the project website
  3. Update the DG: user stories, glossary, NFRs, use cases
  4. Start the next iteration

iP

1 [Optional] Get more out of the iP

If you wish to cite the iP in your resume, you can do more to make it look more impressive to a potential employer. These improvements are not considered for grading and can be done after the semester is over. Some ideas:

  • Improve the GUI: Make the UI look nicer, unique, and memorable. You can get inspiration from what others have done (but remember to give credit if you reuse any code from them).
  • Add a demo video or an animated gif to your user guide to show how the app works.
  • Improve code quality: iP is the right size to cite as an example of your code quality. You can use the RepoSense link (</>) in the iP showcase page to point to your iP code.
  • Add more features.

On a somewhat related note, you can also create similar product websites for your other projects (projects from other courses, pet projects).

tP: Practice iteration → v1.1

Intro to tP Week 7

What's happening this week:

This week, we do the first tP iteration: v1.1.

Each tP iteration focuses on a specific learning outcome, a corresponding product goal, and a strategy that we'll use to achieve both. The ones for this tP iteration (i.e., v1.1) are given below:

v1.1

  • Learning outcome: Able to follow the workflow as a team.
  • Product goal: Update some documents to match the new product direction.
  • Strategy: Practice the workflow while updating the documents.

Aim to do 'just enough': Note how the Product goal (together with the Strategy) is simply a means to achieve the Learning outcome. Unlike in a real SE project, the product in the tP exists only to help you achieve the learning outcome. Hence, aim to do 'just enough' work on the product to achieve the intended learning outcome of the iteration (e.g., don't make features bigger than necessary) so that the tP doesn't add to your workload more than necessary.

We consider this iteration a 'practice' iteration. Reason: As this is the first time your team is working on this codebase, we first focus on learning the workflow that you need to follow as a team. In this practice iteration, we limit ourselves to some document updates only (to minimize the risk of breaking the codebase).

Specifically, we start with a workflow practice session (in task 1), and proceed to do some further documentation updates in tasks 2 and 3.

Things to note:

FAQ What's the deadline for tP iterations?

FAQ What if we overshoot the deadline for a tP iteration?

FAQ What should be in v1.1? Just task 1 or all three tasks?

COMMON MISTAKE: Not following the convention for Git commit message subject.
Caution: This is very hard to rectify later, after the PR containing the commits have been merged. Reason: While Git allows editing past commits, doing so changes their timestamp, which affects your weekly code contribution stats (which are factored into evaluating the consistency of your coding work over the project duration).

COMMON MISTAKE: Forgetting to do each PR from a separate branch (i.e., send PR from the master branch) of your fork. This error means your PR will not be considered as following the forking workflow correctly.

Start using Git via the CLI

If you have been using Sourcetree (or other GUI) for Git before, we strongly recommend that you move towards using the CLI to perform Git tasks in the second half of the semester. Doing so will strengthen your Git knowledge (because CLI takes you closer to what's actually happening, while GUIs might hide such details).
But you can continue to use your favorite Git GUI for a more 'visual' view of your repo, side-by-side with the CLI e.g., from Sourcetree, you can open a gitbash terminal, run the command in that terminal, and see the result in the GUI.

1 Do a 'workflow practice' session Thu, Oct 3rd 23:59

Task: Do a workflow 'practice' session, to get all team members familiarized with the workflow you need to follow in the tP.

Why?: The ability to modify a team-owned codebase in parallel is an important learning outcome of this course. Following a suitable workflow is critical for achieving that. This practice iteration is for you to get used to the workflow that you need to follow in the tP.

Strongly recommended to do this as a team activity (preferably F2F, or else connected via Zoom/MST). That will help you proceed faster (e.g., a PR can be merged soon after it has been created) and will also make it easy for you to help each other w.r.t. to the workflow matters.

Steps:

  1. [one member] Set up the issue tracker of your team repo, if you haven't done so already.
    In addition, create a milestone named v1.1 and set an appropriate deadline (i.e., same as, or earlier than, the iteration deadline)

  1. [each member] Fork and clone the team repo, if you haven't done so already.

  1. [each member] Add your photo to repo while following the prescribed tP workflow. Here are the steps (yes it is a lot of steps for such a small update, but the purpose is to learn the workflow):
  • Read the 'tP Scheduling and Tracking' overview given below.

  • Create an issue to represent the task at hand e.g., Add Jake's photo.

  • Assign the issue to yourself, to indicate you are taking responsibility for it.

  • Assign the issue to the milestone v1.1 to indicate this task is due in v1.1, as given in the panel below.

  • Create a pull request for it, while taking care to follow the workflow prescribed in the panel below. Details of the photo to be added is given below the expandable panel.

  • Icon​​
    Adding a photo
    • Add a suitable photo of yourself, as described here
    • The filename of the profile photo should be
      docs/images/github_username_in_lower_case.png
      Note the need for lower case () e.g. JohnDoe123 -> docs/images/johndoe123.png not docs/images/JohnDoe123.png.
      If your photo is in jpg format, name the file as .png anyway.
  • Get a team member to review the PR. For example, the reviewer can check if,
    the file is in the right location,
    the file name is as expected,
    the PR is sent from a fork, and is from a separate branch,
    commit messages comply with the Git Conventions.

  • Merge the PR.

  • Good job on merging the first PR into the team repo!
  1. [each member] Update the AboutUs page as parallel PRs. In this step, we are going to attempt sending parallel PRs that update the same page, which means there is a potential for merge conflicts (hence, you get to practice resolving merge conflicts in a team project):
  • Create an issue, and a PR, for the following task, similar to steps 3.2-3.5 above (do not merge the PR yet).

Updating the AboutUs page:

This page (in the /docs folder) is used for course admin purposes. Please follow the format closely or else our scripts will not be able to give credit for your work. Similarly, do not split the given .md files further into multiple files, as our grading script will check the given files only.

  • Add your own details.
  • There is no need to mention the tutor/lecturer, but OK to do so too.
  • 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.
  • Wait until all team members have sent the PR for the above step.
    Reviews each other's PRs while waiting.

FAQ What if a team member has not done this task? Can the rest proceed?

  • Merge one of the PRs sent in step 4.1 (e.g., the one that arrived first). If this causes conflicts in other PRs, resolve those conflicts.
    This week's tP briefing video tP Briefing video (Part 2a -- v1.1, Workflow) has a section on how to resolve conflicts in PRs.
  • Merge remaining PRs one at a time, while resolving merge conflicts as needed.
  • Check the AboutUs page in your teams repo to confirm if the page appears as expected. Here is an example.
    If something is not right, you might have to create another PR to rectify it.
  1. Congrats! You are done with this workflow practice session. It might have felt like a lot of 'jumping through hoops' for very little gain but as you go through the tP, this 'workflow overhead' is expected to feel progressively less 'draggy'. Hopefully, it will be almost second nature to you by the time you finish the tP.

2 Update the project website

Now that you have learned the tP workflow, you can proceed to updating a few more tP documents, as per tasks A and B below, following the same workflow (optional to do parallel PRs though).

Recommended procedure for updating docs:

  1. Decide among yourselves who will update which parts of the document(s).
    All team members are expected to contribute to all aspects of documentation (e.g., user docs, developer docs, diagrams)
  2. Update the team repo by following the prescribed workflow:

Guidance on using documentation tools (e.g., How to preview changes locally before committing/pushing) can be found in the relevant section of the Developer Guide of your team project website that you set up earlier. Given below is a shortcut, for your convenience:

FAQ When all members are updating the same document, can we create one issue and assign it to all?

A: Update README page 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. Limit the file to contain one screenshot/mockup only and ensure the new image is roughly the same height x width proportions as the original one. Reason: when we compile these images from all teams into one page (example), yours should not look out of place.
    The UI mock up can be a hand-drawn sketch or created using a tool such as PowerPoint, PlantUML, Figma, etc. Don't spend a lot of time on this, as this will eventually be replaced by a screenshot of the actual product.
    Can we use an AB3 screenshot for this? Only in the unlikely case that your final product UI is expected to look exactly the same as AB3.
  • Update the link of the GitHub Actions build status badge (Build Status) so that it reflects the build status of your team repo.
  • Acknowledge the original source of the code e.g.,
    This project is based on the AddressBook-Level3 project created by the [SE-EDU initiative](https://se-education.org).
  • Update all remaining contents of the page to match your own project.

If you did the above updates correctly, your UI mock up and profile photos should appear in your project website and this Project List Page.

B: Also update site-wide settings, as necessary:

  • You need to update the AB-3 in the top navigation bar of your project website (it's in docs\_config.yml and docs/_sass/minima/_base.scss if using Jekyll; in docs\_markbind\layouts\default.md if using MarkBind).

  • More info on updating site-wide settings such as the above:

3 Update the DG: user stories, glossary, NFRs, use cases

  • Add the following to the DG, based on your project notes from the previous weeks. No need to update other sections, for now.
    Some examples of these can be found in the AB3 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 a few representative use cases (textual form) 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 given project constraints can be considered NFRs. You can add more. e.g. performance requirements, usability requirements, scalability requirements, etc.
    • Glossary: Define terms that are worth recording.

The above DG sections should cover the full requirements of the product, some of which might not even get implemented by the end of this semester i.e., do not limit to just the requirements you intend to implement in the next iteration. Reason: All identified requirements need to be documented for future reference.

Furthermore, these sections will be graded at the final project evaluation, and any bugs in the content can cost you marks at that point. The panel below gives some relevant DG bug examples you can lookout for:

4 Start the next iteration

  • Stronger teams are welcome to stay one week ahead of the tP schedule. So, feel free to move on to next week's tp tasks, and get started on the next iteration (i.e., v1.2).