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:

## 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

In “agile” development, for example, you may create the following Milestones for each sprint:

• sprint 0
• sprint 1
• sprint 2
• sprint 3
• sprint 4

Set the due date of each Sprint to be the day before the following sprint begins.

Assign Milestones to Issues

In Sprint Planning, where an agile development team decides which user stories to tackle for an upcoming sprint, the issues selected for the sprint must be assigned the relevant Milestone in GitHub.

Closing a Milestone

Once a Milestone’s due date has passed, the sprint is over.

Do not retroactively alter the history of a project by removing the original Milestone from the incompleted Issue.

Leave the Issues as-is and feel free to additionally assign a subsequent Milestone to the same Issue.

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.