Apdx E: Using GitHub

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 e.g., in job applications.

2. Strongly recommended: Complete your GitHub profile. In particular,

   • Specify your full name.
   • Upload a profile photo that matches our requirements.
   Why am I being encouraged to complete my GitHub profile?

   ---

3. You are discouraged from changing your GitHub username during the semester/exam/grading period as it can cause our auto-grading scripts to miss your GitHub activities. If you do change your GitHub username during that period, please let us know immediately.

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

tP Team Organization Setup

(/) 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) :AY2122S1-TEAM_ID. e.g. AY2122S1-CS2103T-W12-1, AY2122S1-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-AY2122S1/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 Enable actions button (or the I understand ... enable them 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
   Follow instructions in the Documentation guide page of AB3 developer guide. When set up correctly, your project website should be available via the URL https://ay2122s1-{team-id}.github.io/tp e.g., https://ay2122s1-cs2103-w13-1.github.io/tp.

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

6. 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-AY2122S1/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.

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

tP Workflow

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

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

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

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

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

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

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

    • Bad:Implementing parser  (reason: too big).
    • Good:Implementing parser support for adding of floating tasks

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

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

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

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