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 M1 or Milestone M2, 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 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).
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.
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 main branch, you might use this command to create an iss3 branch and check it out:
git switch -c 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 use this shorter form of push:
git push
And, you can use this shorter form of pull:
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 main 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 main branch into your topic branch (although you may need to manually resolve merge conflicts after the command):
git pull origin main
Once you complete a task, the next thing to do is merge your work into your team’s main branch. To do so, you must submit the work via a GitHub pull request. Then, one of your team’s QA Czars must review the pull request. Once the QA Czar finds the pull request acceptable, they must accept the pull request and merge it into the main branch.
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 main 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 the following commands (assuming that the topic branch is named iss3).
First, the QA Czar must download the latest state of the remote repo, like this:
git fetch
Then, the QA Czar must switch to the iss3 branch, like this:
git switch iss3
Note that this git switch command will automatically set up a local branch iss2 to track the remote branch iss2 from origin.
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 main branch.
If other pull requests are merged into the main 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.
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.
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.
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.