knowledge-kitchen

GitHub for Collaboration

More nuanced usage of GitHub for developer collaboration.

1. Organization
2. Teams
3. README.md
4. CONTRIBUTING.md
5. Issues
6. Labels
7. Milestones
8. Task Boards
9. Conclusions

Organization

Account types

GitHub has two kinds of accounts:

• personal
• organizational

Both types of accounts can host repositories.

Management

A manager maintains an organization account.

The organization’s projects are stored as repositories belonging to this account.

Membership

Personal accounts can be included as members of an organization.

Teams

Teams

An organization can have teams.

Teams are groups of an organization’s members.

An organization manager can assign permissions to a repository to a team as a whole.

README.md

Concept

Every repository has a README.md file, written in Markdown, that automatically renders as the repository’s home page.

This document serves as an introduction to the project to any visitors.

Minimal contents

At a minimum, a README.md document includes:

• a simple description of project
• a short origin story of the project
• a descriptive link to the CONTRIBUTING.md document
• how to build and test the project (once the project reaches that stage)
• any additional relevant links or info

CONTRIBUTING.md

Concept

The CONTRIBUTING.md document, written in Markdown, informs visitors how they can get involved and contribute to the project.

This serves as a sort of contractual agreement among developers and contributors.

Minimal contents

At a minimum, a CONTRIBUTING.md document contains:

• a description of the workflow
• rules: what to contribute, what not to contriute, etc.
• how a new developer must set up their development environment to successfully be able to run the code and work on the project

Issues

Concept

GitHub has a built-in issue management tool.

An issue is usually be a bug to fix or a feature to implement.

Agile issues

In “agile” software development, an issue is of one of the following types:

• User story - a user requirement, written in a specific style
• Task - one unit of work towards a user story
• Spike - a bit of work that does not directly relate to a user story

Product Backlog

In “agile” software development, the full set of user stories make up the “Product Backlog”.

User Stories

User story issue titles are written in the style,

As a ___, I want to ___, so that ___

The issue description can also optionally include an Estimation of Effort and Acceptance Criteria.

Issue Descriptions

GitHub allows you to use Markdown to format issue descriptions, including a checklist for Acceptance Criteria.

Title:

As a professor, I want to automatically send students their grades so I don't have to do it.

Description (note this example uses “tee shirt sizing” and Markdown checkbox syntax):

## Estimation of effort

XS

## Accceptance criteria:

- [ ] foo
- [ ] bar
- [ ] baz

Labels

Concept

Any GitHub issue can be tagged with arbitrary labels.

This allows you to easily view all issues with a common label.

No issue should be without a label.

Minimal contents

For agile software development, at a minimum, the following labels should be available to apply to any issue:

• user story to label user stories
• task to label tasks
• spike to label spikes

Milestones

Concept

GitHub allows Issues to be associated with particular Milestones.

This is used to indicate which Issues must be resolved in order for the milestone to be considered complete.

Sprint Milestones

Milestones are especially useful in Agile development, where work is earmarked for particular Sprints.

• individual Issues can be added to particular Milestones

The Milestones view shows progress towards each Milestone, including:

• percent completion
• number of open issues
• number of closed issues

Sprint Milestones (continued)

The problem with GitHub’s Milestones: GitHub’s project management tools include “Milestones”, which are tags that can be associated with any Issue. For example, you could use this to create a “Sprint 1” Milestone and mark User Stories that you intend to work on during Sprint 1 with this milestone. In GitHub, only one Milestone can be associated with any Issue. But we will often start work on a User Story during one Sprint but continue working on it in the next. So, we would need to mark that User Story as being related to multiple Sprints. GitHub’s Milestones feature doesn’t work for us.

Sprint Milestones (continued again)

The solution: Instead, use GitHub’s Labels feature to allow associating any given User Stories one or more Sprints, as needed. You can add as many Labels to a given Issue as you wish.

What to do: Each team must have a set of Labels to represent each Sprint within GitHub’s Issues tracker:

• Sprint 0
• Sprint 1
• Sprint 2
• Sprint 3
• Sprint 4

Once a particular Sprint has begun, all Issues representing User Stories, Tasks, or Spikes that have been decided to be addressed within that Sprint must be assigned to the proper Label representing that Sprint.

Task Boards

Concept

GitHub contains a tool to create Kanban-style Task Boards.

A Task Board shows the current status of all issues asssigned to a given sprint.

One look at this board shows what has been done, and what is left to do.

Columns

A Scrum task board must have the following columns:

• Sprint backlog (User Stories) - the Sprint Backlog
• To do (Tasks) - The Tasks that have not been begun
• In progress (Tasks) - The Tasks that are currently being worked on
• Awaiting review (Tasks) - The Tasks are done but need someone to review them
• Done (Tasks) - The Tasks that have are done and passed review

Closing a tasks board

Do not retroactively alter the history of a project by changing anything in a task board once the relevant sprint is over.

• leave all incomplete Issues as they are in the Task Board
• feel free to add those same Issues onto a new Task Board for a subsequent Sprint

Conclusions

Thank you. Bye.