GitHub Task Management

This document defines the guidelines we follow for task management using GitHub Issues. It is intentionally lean and covers primarily how individual releases are managed.

Introduction

Issues typically flow through the below states during their lifecycle.

Most states are controlled via GitHub labels. By default, state transitions are managed simply by removing the current state label and applying the appropriate next state label. The exception are the Backlog and Done states. State labels do not control these states. Rather they are controlled by being Open or Closed, and whether they are assigned to a milestone. That rule applies regardless of any labels assigned to it.

States

Any issue with a label is automatically excluded from the below states.

State	Label	In a Milestone?	Issue State	Progress	Description
Backlog	n/a	✗		0%	Issues have been identified but are not yet ready for development.
Analysis	state-analysis	✓		10%	Issues are actively being analyzed, typically by a Business Analyst or Lead Developer, to ensure the work is Ready for development.
Ready	state-ready	✓		20%	Issues have been fleshed out to the point where they are believed to be ready to be acted upon by developers working on the associated milestone.
Test Failing	state-test-failing	✓		30%	The tester failed the implementation. It is assumed that failed items went through code review, so they inherit the percent complete from Code Review.
In Development	state-in-development	✓		30%	Issues are actively being worked on by a developer. With the exception of items that are blocked or returned to development due to failed tests, each developer should strive to have as few items in this state as possible.
Code Review	state-code-review	✓		70%	The developer believes he/she is complete and has submitted the issue for peer review.
Feature Testing	state-feature-testing	✓		80%	Issues are code complete and can be acted on by testers. All code is assumed to be checked in and deployed to the appropriate environments for testing.
Integration Testing	state-integration-testing	✓		90%	Issues have been unit tested and are ready for closure pending end of sprint integration testing.
Done	n/a	n/a		100%	Issues have passed testing and are closed.

Testing

Integration Testing

Items in the integration testing state have passed all unit tests in the development environment and are considered complete pending final end of phase integration testing. Once all development work for the sprint has been completed, items will be integration tested before being moved to Done.

Failed Tests

When a test fails, in addition to moving the item back to In Development, the tester should apply the Test Failing label and re-assign the issue to the original developer. This will aid in tracking priorities and help developers identify what needs their immediate attention.

Schematic

Labels

The only thing that you need to configure to use this process is to add the below labels to your repo.

Import labels

This bash script can be used to:

• Remove the default GitHub labels automatically adds when a repo is created.
• Add the above process labels.

The script requests a GitHub Personal Access Token which in order to access private repos. You will need to first create a token by following these instructions.

To run the script:

1. Download (or git clone the repo)
2. Set execute permissions: chmod +x ./set-github-labels.sh
3. Drag the file into Terminal or execute by typing ./set-github-labels.sh

Manually add the labels

The following can be used for configuring the label names and colors:

State labels

	Label	Color	Description
	state-analysis	#dd7404	See state description above
	state-ready	#ec9f04	"
	state-test-failing	#f5ba04	"
	state-in-development	#fbca04	"
	state-code-review	#b3bb02	"
	state-feature-testing	#59a901	"
	state-integration-testing	#009800	"

Priority labels

	Label	Color	Description
	priority-high	#0aff2f	High priority
	priority-med	#85ff97	Normal priority
	priority-low	#adffba	Low priority

Type labels (optional)

	Label	Color	Description
	type-bug	#b60205	Bug / Error
	type-enhancement	#5b2a68	Enhancement / Feature request
	type-documentation	#2740a1	Project documentation (README.md/Wiki/Javadoc/...)
	type-question	#1d76db	Questions about the project

Flag labels

	Label	Color	Description
	flag-trash	#006b75	An issue that is deleted but not Done (since you cannot delete an issue in GitHub Issues)
	flag-invalid	#006b75	Issue that has doesn't conform to the contribution guidelines (ISSUE_TEMPLATE.md) or spam
	flag-duplicate	#006b75	Issue that already exists
	flag-wontfix	#006b75	Issue that won't be implemented
	flag-requirement	#006b75	Formal requirement
	flag-help-wanted	#006b75	"Can someone help me?"
	flag-breaking-change	#006b75	Breaks the current API
	flag-device-specific	#006b75	Issue that only occurs on some devices

Scheduling the project

Follow this scheme to schedule releases in GitHub:

1. Create a Milestone for every two weeks
   • Name the project in the format "Release [#.##]", e.g. "Release 0.01"
   • Select the Due Date
   • Add a brief description of the milestone
2. Assign issues to each milestone
3. Create an overall project schedule using milepost.
4. When satisfied with the schedule, email to the team and evenutally the client.