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.
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 1 or Milestone 2, as appropriate.
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:
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” 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).
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.
To declare who will perform the special (A&B eligible) roles, your team must create a special roles GitHub issue. Your team should create only one such issue per iteration. It should be filled out as follows:
Title: The issue title must be set to “Milestone 1 Special Roles” (incrementing the milestone number as appropriate).
Comment: The issue comment must use the Markdown template below. At this stage, the Project Coordinator and Quality Assurance Czars must be declared. However, the video and demo roles may be filled in at the end of the iteration as an edit to the issue.
Assignees, Labels, Projects: Leave all of these fields blank.
Milestone: The milestone must be set to the current GitHub milestone for the iteration.
Markdown Template for Issue Comment:
- Project Coordinator: xxx (Team Member Name)
- Quality Assurance Czars:
- xxx (Team Member Name)
- xxx (Team Member Name)
- Video Demo Creators:
- xxx, 999 (Team Member Name, Number of Points; filled in at end of iteration)
- xxx, 999 (Team Member Name, Number of Points; filled in at end of iteration)
- Demo-Booth Operator: xxx (Team Member Name; filled in at end of iteration)
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 iss3The 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 iss3After you run the above push command, you can push and pull from the branch using the shorter forms:
git pushgit pullWith the topic branch is 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 masterOnce 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.
Reviewers: You must set the reviewers to your team’s QA Czars for the iteration, that is, the ones who will review pull requests.
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 origingit checkout -b iss3 origin/iss3If 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.
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.
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.