Project Workflow Instructions

In this document, I will explain the workflow to follow for doing project work in this course. The workflow mostly follows the popular GitHub Flow workflow.

1. Beginning an Iteration

1.1. Create a GitHub Milestone

At the start of each iteration, your team must create a milestone for the iteration in GitHub. Here is a GitHub Help article on milestones. You need to do this only once per milestone in GitHub. Each GitHub milestone is used to group issues and pull requests that contribute to a particular milestone. Name the Github milestone Milestone M1 or Milestone M2, as appropriate.

1.2. Create Tasks as GitHub Issues

In addition to creating a GitHub milestone, your team must also create tasks for each team member to perform at the start of each iteration. There are three categories of tasks:

• US implementation tasks. These tasks are mainly concerned with adding features that satisfy one user story. The task will either aim to completely implement the user story or to at least implement some substantial portion of it. Thus, for our purposes, US implementation tasks and user stories will be synonymous.
• SUPPORT implementation tasks. These are substantive development tasks that support multiple USs, and thus, don’t fit well as being part of any one US. For example, setting up Devise authentication and setting up Bootstrap styling come to mind here.
• HOTFIX debugging tasks. These tasks are concerned with fixing defects in the existing features.

Once you have chosen the tasks for your team and assigned them to team members, you must create an issue in GitHub for each of your tasks. The issues must be filled out as follows:

• Title: For US implementation tasks, the title must begin with US ID and contain the title of the US to be implemented. For example, an issue might have the title “US3 Update Profile”. For SUPPORT tasks, the title must begin with “SUPPORT:” followed by a title for the task. For example, an issue might have the title “SUPPORT: Set up Devise”. Similarly, for HOTFIX tasks, the title must begin with “HOTFIX:” followed by a title for the task. For example, an issue might have the title “HOTFIX: Dead profile link on home page”. If a task was worked on during a previous iteration, but only partially completed, the new issue should append “(part 2)” to the end of the title (incrementing the number as appropriate).

• Comment: The issue comment must document a task description and evaluation instructions.
  • In particular, you must create a section called Task Description in which you answer the following questions: What work will you complete by the end of the iteration? What code or artifacts will you contribute to the project? You may also comment on the challenge/difficulty of the task if you feel that it’s inobvious and important.
  • You must also create a section called How to Evaluate that answers these questions: How should the instructor evaluate that you completed the task at a high level of quality? What evidence should the instructor look at?

• Assignees: The assignees must be set to the team member who plans to perform the task.

• Labels: The labels must be set to enhancement if the task is developing new features/functionality. They must be set to bug if the task aims to fix a bug in existing functionality.

• Projects: N/A. We won’t be using GitHub projects in this course.

• Milestone: The milestone must be set to the current GitHub milestone for the iteration.

2. Performing Tasks

For each task you work on, you will perform your work in a topic branch. The branch must have a name of the form iss3 where the associated GitHub issue number is 3.

As a reminder, here some Git commands that you will likely find handy.

From the master branch, you might use this command to create an iss3 branch and check it out:

git checkout -b iss3

The first time you push the topic branch, use this command to set the upstream branch (assuming that the topic branch is named iss3):

git push -u origin iss3

After you run the above push command, you can push and pull from the branch using the shorter forms:

git push
git pull

With the topic branch checked out, make changes, commit them locally, and push them to GitHub. All changes made this way should be fully contained in the topic branch.

If other teammates merge changes into the master branch while you are working on your topic branch, you will need merge those changes into your topic branch before you’re done. From your topic branch, you can use this command to merge the remote master branch into your topic branch (although you may need to manually resolve merge conflicts after the command):

git pull origin master

3. Contributing Code to the Project

Once you complete a task, the next thing to do is merge your work into your team’s master branch. To do so, you must submit the work via a GitHub pull request.

Create the pull request as follows:

• Title: The title must be set the same as the corresponding issue title. Additionally, if the planned task (as documented in the issue) was fully completed, you must append “(completed)” onto the end of the title. If that task (as planned) was only partially completed, you must append “(partial)” onto the end of the title.

• Comment: The pull request comment must have two things.
  • First, you must add a line “Closes #3” (assuming that the issue is issue #3) to the comment. This will link the pull request with its corresponding issue and will automatically close the issue when the pull request is closed. Here is a GitHub Help article on using keywords in pull request comments to close issues.
  • Second, it must have section call Task Outcome that must answer the following questions: How did the task turn out? With respect to the above evaluation criteria, what should the instructor expect to find now that the iteration is over? Any further evidence for confirming that the task was completed well?

• Reviewers: You must set the reviewers to your team’s QA Czars for the iteration, that is, the ones who will review pull requests.

• Labels, Milestone: You must set the labels and milestone to be the same as they were in the issue.

It is the job of one of your team’s QA Czars to review your pull request. They must test it to make sure that it works and confirm that it can be fast-forward merged with the master branch. They must post comments or change requests if they find issues. To test the code, the QA Czar can pull the branch to their local repository and check it out using these commands (assuming that the topic branch is named iss3):

• git fetch origin
• git checkout -b iss3 --track origin/iss3

If changes are needed, the author of the topic branch must make them to their working copy and push them to GitHub (all still in that topic branch). The pull request will be automatically updated to reflect the changes. The author will probably also want to reply to the comment in the pull request, so the QA Czar is notified of what’s happened.

Once the QA Czar approves the change, they should also merge it into the master branch.

If other pull requests are merged into the master branch before yours is, you will need to merge those changes into your topic branch before your pull request can be merged.

4. Unplanned Bug-Fixing Tasks

If a bug arises in the middle of an iteration, you should essentially follow the same major steps described above to contribute a fix. For example, like above, you should first create an issue for the bug-fixing task, then do the work in a topic branch name after the issue number (e.g., iss3), and finally submit the work as a pull request.

5. Criteria for Task Reporting

A key goal of this workflow is ensure that the tasks performed by each team member are fully and completely reported. Here are some important criteria to take into account when planning and reporting tasks:

• Plan Enough Work: Each team member must take on a “reasonable” amount of work each iteration. For example, for a 3-week iteration, the work a team member takes on must be appropriate for a 3-week homework assignment. In order to achieve a reasonable amount of work, a given team member may need to specify multiple tasks.

• Everybody Codes: For each development iteration, each and every team member must take on substantial coding tasks (although not all tasks need to involve coding).

• No Shared Tasks: Do not list the same task for more than one team member. Although team members are encouraged to collaborate, the responsibility for completing a particular task must lie with one and only one team member.

• Cross-Reference Design Documents You must cross-reference design documents and UI sketches to make it clear what each task involves. (That implies that you will give each design artifact a unique name to which you can refer.) Such cross-references may appear in any part of the task report (i.e., Task Description, How to Evaluate, or Task Outcome).

• What Will Be Built?: You must describe to the best of your ability what project artifacts will be built. That means telling about things like controller classes, controller actions, model classes, view ERBs, etc.

• No Learning-Only Tasks: It is assumed that team members will need to put effort into learning new technologies during the project. However, such effort should not be specified as a task. Generally, only specify tasks that yield project artifacts.

• No Communication Tasks: It is assumed that team members will put effort into team communication and coordination each iteration. These types of effort should not be counted as tasks. Generally, only specify tasks that yield project artifacts.

• Evaluation Instructions: In specifying how the instructor should evaluate a task, keep the following in mind. Tasks must be verifiable. The instructor must be able to quickly and conveniently verify that a task was performed and assess how good of a job was done on it. The instructor must feel confident that no loophole or misrepresentation was exploited that would lead to an inaccurate evaluation.