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

Apdx D: Getting HelpApdx F: Handling Team Issues


Apdx E: Using GitHub

Creating a GitHub Account

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

  1. Choose a sensible GitHub username as you are likely to use it for years to come in professional contexts e.g., in job applications.

  2. Recommended (but not required): Complete your GitHub profile. In particular,

    • Specify your name.
    • Upload a profile photo that matches our requirements.

    Why am I being encouraged to complete my GitHub profile?

  3. Please do not change your GitHub username during the semester/exam/grading period as it can cause our auto-grading scripts to miss your GitHub activities. If you change your GitHub username during that period due to an unavoidable reason, please let us know immediately.

Guidelines for Reviewing PRs

Follow the Best practices for reviewing PRs @SE-EDU/guides. You are expected to follow all of them.

tP Team Organization Setup

Please follow the organization/repo name format precisely or else our grading scripts will not be able to detect your work.

(/) Only one team member:

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

  • Create a GitHub organization with the following details:
    • Organization name (all UPPER CASE) :AY2324S1-TEAM_ID. e.g. AY2324S1-CS2103T-W12-1, AY2324S1-CS2103-T09-2
    • Plan: Open Source ($0/month)
    • This organization belongs to: My personal account
  • Add members to the organization:
    • Create a team calleddevelopersto your organization.
    • Add your team members to the developers team.

tP Team Repo Setup

(/) Only one team member:

  1. Fork the https://github.com/nus-cs2103-AY2324S1/tp repo to your team org.

    • This repo (let's call it the team repo) is to be used as the repo for your project.
    • Please do not rename the fork Reason: our grading scripts rely on the repo name.

  2. Enable the issue tracker.

  3. Enable GitHub Actions: Go to the Actions tab and enable workflows by clicking the button (or the button). That will enable the GitHub Actions that are already included in the repo you forked.
    Set up codecov, as explained in the DevOps guide.

  4. Set up the project website
    There are two options for the project website: Jekyll, MarkBind. You can choose either one. More info are given in the panels below:

Jekyll

Pros:

  • Widely used (one of the most popular static site generator tools)
  • Built-in support by GitHub

Cons:

  • More optimized for blogs (but can be used for normal websites as well)
  • Local installation is more troublesome (requires Ruby)

Example AB3 website using Jekyll: here

How to set up: Follow instructions in the Documentation guide page of AB3 developer guide.

MarkBind

Pros:

  • Optimized for creating course/project websites -- also used by CS2103/T website
    e.g., Built-in support for PlantUML, and many other features useful for project documentation
  • Easier to set up locally (and JavaScript based, rather than Ruby)

Cons:

  • Home-grown, small user base

Example AB3 website using MarkBind: here

How to set up:

  1. Merge the given switch-docs-to-markbind branch to the master branch.
  2. After that, follow instructions in the this se-edu/guide.

When set up correctly, your project website should be available via the URL https://ay2324s1-{team-id}.github.io/tp
e.g., https://ay2324s1-cs2103-w13-1.github.io/tp.

  1. Add members. Ensure your team members have the desired level of access to your team repo.
    Recommended: Give admin access to 1-2 members and write access to others.
  2. Create a team PR for us to track your project progress: i.e., create a PR from your team repo master branch to [nus-cs2103-AY2324S1/tp] master branch. PR name: [Team ID] Product Name e.g., [CS2103-T09-2] InsureList. 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.
    Please fill in these details as specified because they are used by our grading scripts.
    • PR subject: the name of your product e.g., [CS2103-T09-2] InsureList
    • Description: a 1-2 sentence overview (plain text only, no formatting or links) of your project indicating the target user and the value proposition e.g., InsureList helps insurance agents manage detail of their clients. It is optimized for CLI users so that frequent tasks can be done faster by typing in commands.

tP Issue Tracker Setup

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

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

Issue type labels:

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

Priority labels:

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

Bug Severity labels:

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

When applying for documentation bugs, replace user with reader.

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

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

tP Individual Fork Setup

(, , , ...) Every team member:

  1. Watch the tp repo (created above) i.e., go to the repo and click on the button to subscribe to activities of the repo.
  2. Fork the tp repo to your personal GitHub account.
    Please do not rename the fork Reason: our grading scripts rely on the repo name.
  3. Clone the fork to your computer.
  4. Set up the developer environment in your computer by following the Setting up and getting started page of AB3 developer guide.

Do not alter these paths in your project as our grading scripts depend on them.

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

tP Workflow

Read our reuse policy (in Admin: Appendix B), in particular, how to give credit when you reuse code from the Internet or classmates:

  • Follow the forking workflow in your project. Normally, we expect you to follow the forking workflow at least until (and including) v1.2 after which you may tweak the workflow v1.3. However, after following the forking workflow for 2-3 PRs (per person) in v1.2, if you are confident that you can follow the forking workflow well, you may switch to the feature branch workflow workflow .
  • Protect the master branch: You can use GitHub's Protected Branches feature to protect your master branch against rogue PRs. We suggest the following:
    • Go the the settings of your team repo.
    • Click on the Branches option on the navigation menu on the left.
    • Click the button. In the Branch protection rule page,
      • Specify the Branch name pattern to be master
      • Tick the option Require status checks to pass before merging to ensure that a branch has to pass CI before it can be merged into the master branch
      • If you think all PRs should be reviewed by someone other than the PR author before they are merged, also tick the Require pull request reviews before merging option.
  • Create issues to represent project tasks so that they can be tracked using the issue tracker features.
  • Create a PR when you implement a project task that updates the code.
    ALERT Don't forget to send each PR from a separate branch, as that is an essential part of the forking workflow.
    You can use GitHub's draft PRs feature to indicate that a PR is not yet ready for merging.
  • Get team members to review PRs. A workflow without PR reviews is a risky workflow.
    • Follow the Best practices for reviewing PRs @SE-EDU/guides.
      PRO TIP LGTM is common abbreviation you can use in the review comments to mean Looks Good To Me.
    • While waiting for one PR to be merged, you can send more PRs. If you do, remember to use a separate branch for each PR, and try to reduce overlaps between parallel PRs (so that each can be reviewed/merged independently from each other).
  • Go breadth-first iterative: As you are expected to follow breadth-first iterative approach, almost all code additions to the master branch should take the product from a working version to a slightly better working version.
    • Bad Let's add all data classes first reason: this is the depth-first approach
    • Bad Let's finish the part of the code that saves and loads data first reason: this is the depth-first approach
    • Good Let's add code to support simple todo tasks first (i.e., read, delete, save, load)
  • Do not merge PRs failing . The CI status of a PR is reported at the bottom of the conversation tab of the PR page. Here's an example:
    • If there is a failure, you can click on the Details link in corresponding line to find out more about the failure. Once you figure out the cause of the failure, push a fix to the PR.
    • An exception to this guideline is when the failure is confirmed to be due to something you can afford to ignore e.g., when CI fails due to a drop in code coverage but the code section that is causing the coverage drop is not practical to be covered by automated tests or you plan to write the relevant tests at a later time.
  • Avoid rebasing/squashing when merging PRs. While both are good alternatives to the default behavior of creating a merge commit, rebasing/squashing can affect the timestamp of the commits, which can interfere with the progress tracking that we do for grading purposes i.e., the commits can get detected under a week different from the week they were actually done.
  • After merging a PR,
    • close the corresponding issue.
      PRO TIP You can use GitHub's Fixes #123 trick to get the issue to close automatically when the PR is merged.
    • sync your individual repos/forks with the team repo as follows:
      • Pull the latest master from the team repo, and push it to your own fork.
      • If there are any unmerged branches in your local repo, for each of them,
        merge master branch to it, and push the updated branch to your fork.
        Another way to sync a branch with the master branch is to rebase it. But we discourse that approach as it will change the timestamp of your branch commits, affecting how our grading scripts track your work.
    • don't delete the branch used by the PR. While it is common practice to delete a branch after merging it, we require you to keep those branches in the team repo so that our scripts can confirm that you used branches when adding changes.

After following the given workflow for at least , optionally, you may adjust the process rigor to suit your team's pace. Here are some examples:

  • Switch to a lighter workflow:

    • While forking workflow is the safest (and is recommended), it is also rather heavy. You may switch to a simpler workflow if you wish. Refer the textbook to find more about alternative workflows:
      • The feature branches workflow: a reasonable alternative, but if you choose this, make sure your master branch is protected and most members have write access only (i.e., no admin access)
      • The centralized workflow: discouraged.
    • Even if you do switch, we still recommend that you use PR reviews, at least for PRs affecting others' features.

  • Reduce automated tests: Automated tests have benefits, but they can be a pain to write/maintain.
    It is OK to get rid of some of the troublesome tests and rely more on manual testing instead. The less automated tests you have, the higher the risk of regressions; but it may be an acceptable trade-off under the circumstances if tests are slowing you down too much.
    There is no direct penalty for removing tests. Also note our expectation on test code.

  • Reduce automated checks: You can also reduce the rigor of checkstyle checks to expedite PR processing.

  • If you are unsure if a certain adjustment is allowed, you can check with the teaching team first.

tP Project Schedule Tracking

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

Using Issues:

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

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

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

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

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

In both cases, apply the type.Story label.

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

  • Formalize the project plan by assigning relevant issues to the corresponding milestone.

  • Define project tasks as issues. When you start implementing a user story (or a feature), break it down to smaller tasks if necessary. Define reasonably sized, standalone tasks. Create issues for each of those tasks so that they can be tracked.

    • A typical task should be small enough for one person to do in a few hours. eg.,

      • Bad (reasons: not a one-person task, not small enough): Write the Developer Guide
      • Good: Update class diagram in the Developer Guide for v1.4

    • There is no need to break things into VERY small tasks. Keep them as big as possible, but they should be no bigger than what you are going to assign a single person to do within a week. eg.,

      • Bad:Implement parser  (reason: too big).
      • Good:Implement parser support for adding events

    • Do not track things taken for granted. e.g., push code to repo should not be a task to track. In the example given under the previous point, it is taken for granted that the owner will also (a) test the code and (b) push to the repo when it is ready. Those two need not be tracked as separate tasks.

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

      • Omit redundant details. In some cases, the issue title is enough to describe the task. In that case, no need to repeat it in the issue description. There is no need for well-crafted and detailed descriptions for tasks. A minimal description is enough. Similarly, labels such as priority can be omitted if you think they don't help you.

  • Assign tasks (i.e., issues) to the corresponding team members using the assignees field. Normally, there should be some ongoing tasks and some pending tasks against each team member at any point.

Using Milestones:

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

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

  • Issues assigned to the milestone, team members assigned to issues: Used GitHub milestones to indicate which issues are to be handled for which milestone by assigning issues to suitable milestones. Ensured issues are assigned to team members. Note that you can change the milestone plan along the way as necessary.

  • Deadline set for the milestones (in the GitHub milestone). Your internal milestones can be set earlier than the deadlines we have set, to give you a buffer.

Wrapping up a Milestone:

  • A working product tagged with the correct tag (e.g. v1.3) and is pushed to the main repo or a product release done on GitHub (example).

  • CI passing for the version tagged/released.

  • Milestone updated to match the product i.e. all issues completed and PRs merged for the milestone should be assigned to the milestone. Incomplete issues/PRs should be moved to a future milestone.

  • Milestone closed.


Apdx D: Getting HelpApdx F: Handling Team Issues