Github Workflow

In CS 490, we’ll use a common Github workflow employed by many open source and corporate projects.

You have probably already used git and Github extensively in your previous courses. However, things change when you work as a team. This tutorial is a great resource for leveling up your git skills.

This document provides an overview of the workflow we’ll use on Github.

Creating an Organization

• Create an organization for your team. An organization can contain multiple git repositories and is owned by multiple accounts, allowing easy collaboration and administration.

  • Add teammates, course staff, and sponsor(s) to the organization.
  • Your organization will be visible to the public. Create a .github repository (a “special” repo that contains organization information) and populate .github/profile/README.md with some information about your team and project.
    • HINT: There is a link on the organization landing page that will help you create this if you don’t have one already.
  • Note that the repositories you create under your organization can be private – please ensure you choose based on your sponsor’s preference (your sponsor will own the intellectual property (IP) associated with this project).

• Create at least one repository for your code. As your project evolves, you may want to add more (e.g., backend repo, frontend repo, etc).

• Create a new Project under your organization using the Team Planning template. You will use this to track each teammate’s status, workload, and contributions.

Project Management

Once your project goal is clear and you have developed milestones to complete, it’s important to spend time planning and tracking your progress.

• Everything you do on the project must start as an issue in your bug tracker(s).
• Add new items to your Team Planning page, select them, and choose Convert to Issue. Next, choose the repository that the issue should be assigned to.
  • Assign at least one team member to the issue.
  • Choose relevant labels (bug, enhancement, documentation, etc.)
  • Choose the target iteration for the issue
  • We’ll be using short one week sprints/iterations in this course. Issues should generally not span more than one week; if they do, consider breaking them into smaller sub-issues.
• Project items become issues, issues are the basis of new code branches, and branches become pull requests are eventually merged into the main branch after they are code reviewed by at least one teammate.
  • Do not merge/review your own pull requests.
  • Issues that are addressed and closed via commits and code reviews will be automatically resolved to “Done” within your project tracker.

Development

As noted above, you should NEVER commit directly to the main branch of any of your project repositories. If you want to change something, you need to create a new issue and new branch for the work you will do.

• We will use a single mainline git workflow. Branches are short-term so branch early, branch often.
• Once you’ve created a branch for your work, make sure you switch to it before making committing code.
  • Commit messages should be written in imperative style (e.g., “Enable feature X” instead of “Enables feature X,” “Enabling feature X”, “Committing, lolz”, etc.)
  • Commits should be small and ideally each commit should compile cleanly. You can use git add -p for patch mode wherein you select small chunks of code for the commit, or use your IDE’s git UI.
  • When relevant, you should reference issue numbers and pull request numbers in your commit messages (e.g., “Add configuration option for #23”).
  • Don’t forget to push your work. Since this is your own branch, you won’t impact your teammates.
• When the issue is resolved, commit and push your work. Then submit a pull request from your development branch referencing the relevant issues.
• Never merge your own pull requests. Another teammate must perform a code review on your work and merge it if it’s ready to be in the main branch. Otherwise, the teammate will suggest changes and fixes that must be applied before the pull request can be merged.