GitHub for Collaboration

# GitHub for Collaboration

More nuanced usage of GitHub for developer collaboration.

---

# Agenda

1. [Organization](#organization)
2. [Teams](#teams)
3. [README.md](#readme)
4. [CONTRIBUTING.md](#contributing)
5. [Issues](#issues)
6. [Labels](#issues)
7. [Milestones](#milestones)
8. [Task Boards](#task-boards)
9. [Conclusions](#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](https://www.markdowntutorial.com/), 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](#contributing) 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](/content/courses/agile-development-and-devops/slides/scrum/#agile-manifesto)" 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:

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

Description:

```markdown
## Estimation of effort

## 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](/content/courses/agile-development-and-devops/slides/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.