Skip to content

Instantly share code, notes, and snippets.

@monkut

monkut/github-organizational-project-management.md

Last active January 21, 2019 09:06
Show Gist options
  • Save monkut/4b608e6c8e42ac61b94b39abcecd6e94 to your computer and use it in GitHub Desktop.
Save monkut/4b608e6c8e42ac61b94b39abcecd6e94 to your computer and use it in GitHub Desktop.
Download ZIP
My method of development with a team.
Raw
github-organizational-project-management.md

Purpose

This page describes how a project is managed using github organizational projects

Project Repository Branch Workflow

github flow is used for development.

When an "Assignee" takes a task, they create a "Feature branch" and develop their code in that branch. When task is complete a PR (Pull Request) is created. A PM or Lead (and relevant project members) reviews the PR, when the PR passes review a PM or Lead will merge the PR into the master branch.

Terms

  • Github Organizational Project:

    • A github project that allows multiple repository issues to be tracked in the same project for github organizational accounts.

  • Task:

    • A github "issue" linked to a specific repository. Used inter-changably with "Issue"

  • Issue:

    • A github issue linked to a specfic repository.

  • Column:

    • A container for issues within a project. Used to identify the status of the issue.

  • Label:

    • Github label that describes something about the Issue it is applied to. Allows filtering.

  • Note:

    • A Github project "Note" item.

  • Card:

    • An "Issue" or "Note" in a project column.

  • PM:

    • Project Manager

  • Lead:

    • Project Lead

  • Assignee:

    • Person assigned to a specific Task.

  • PR:

    • Github Pull Request

Adding an issue to an Organizational Project

There are 2 methods to add an Issue to a Github Organizational Project.

Add Issue via Note (Create new Issue)

  1. From the column to which you want to add the Task, click the "+" icon.

    • A "Note" is created

  2. Enter title for Task in the "Note", and click the "Add" button.

    • This will create a "Note" item in the column.

  3. On the created "Note", click the "..." icon, and click, "Convert to Issue".

    • The "Convert to Issue" dialog will open.

  4. From the "Convert to Issue" dialog, search for and select the appropriate repository to which the issue should belong, add issue details and click the "Convert to Issue" button.

    If uncertain of which repository the issue should belong to ask the project lead.

Add Issue via existing Issues

Pre-existing Issues can be added to the project via the "Add Card(s)" button on the upper-right side of the project page.

  1. Click the "Add Card(s)" button

    • An issue search dialog will be displayed.

  2. Search for and find the issue you want to add.

  3. Drag and Drop the Card for the issue you want to add to the project into the desired column.

Github Project Structure

A github organizational project consists of "columns" containing "Cards". Cards can be Issues, Notes or PRs. For this project we only use "Issue" cards.

Where the name of the column is used to describe the state or condition of the Tasks it contains.

Defined Columns

The following columns are defined for the project.
The state of Tasks is defined by column in which they exist.

Tasks flow generally from left (planning) to right (done) as they are completed.

  • backlog:

    • Contains Tasks that we may want to do eventually but are not required for the current phase

  • planning:

    • Contains Tasks that intended to be completed in the current phase.
    • Typically a Task will start here.
    • A specific user should be "assigned" to a task in this state. (Assignments should be freely changed to reflect actual development)

  • in-progress:

    • Contains Tasks being actively developed but not finished.
    • A specific user should be "assigned" to a task in this state.(Assignments should be freely changed to reflect actual development)

  • done:

    • Contains completed/closed tasks.

Repository Labels

Each repository within the project contains the labels described here. These labels are pre-defined in order to post-process issues to get a better understanding of the state of the development activities.

In order to assure that each repository in the project has the same set of "labels", a separate tool is used to update and manage the labels. If you want to add a label let "Shane" know and it will be added so that the addition will be added to all related repositories.

Label Types

  • "category:*"

    • (Required)
    • Describes what type of Task the issue is.
    • All Issues must have a "category:*" label assigned.

  • "estimate:*"

    • (Required if planning or in-progress)
    • Defines the estimated number of work days remaining to complete the task.
    • Issues in planning or in-progress columns must have an "estimate:*" label assigned.
    • This label should be updated weekly (or more frequently) for Tasks in the in-progress column.

  • "flag:*"

    • (Optional)
    • Defines additional labels intended to flag or additional information to an Issue.

  • "req:*"

    • (Optional)
    • Links an Issue to a specific requirement number
    • Applied to Issues where the issue clearly covers a specifically defined requirement

  • "cancel:*"

    • Applied to Tasks deemed unnecessary.
    • Provides a reason a Task was cancelled.

Labels

The following labels are applied to all repositories being tracked by the project:

Category Labels
  • category:analysis
  • category:bug
  • category:data-preparation
  • category:design
  • category:documentation
  • category:feature
  • category:feature-enhancement
  • category:setup
  • category:study
Estimate Labels
  • estimate:1d
  • estimate:3d
  • estimate:5d
  • estimate:7d
  • estimate:10d
  • estimate:15d
  • estimate:30d
Flag Labels
  • flag:blocker
  • flag:help-wanted
  • flag:question
  • flag:needs-attention
Cancel Labels
  • cancel:duplicate
  • cancel:invalid
  • cancel:wontfix

Issue Life-cycle

Tasks(Issues) follow the following life-cycle for the duration of the project.

Standard Development Task Life-Cycle

  1. PM/Lead creates Task and adds it to the planning column.

    • Appropriate "estimate:*" is applied.
    • Assignee is assigned (Should be the person expected to complete the task)

  2. "Assignee" selects a task to start, and moves it to the in-progress column.

    • Creates the feature branch for development.
    • Assignee updates the "estimate:*" label if estimate has changed or better understood.

  3. "Assignee" completes coding, issues a PR for review.

    • Requests review from PM/Lead and relevant project members

  4. PR is reviewed by a PM/Lead and relevant project members, when the PR passes review, the PR is merged to master by a PM or Lead.

  5. PM/Lead moves the task to the "done" column when PR is merged to master.

For non-coding tasks the PR portion is ignored, but follows the same life-cycle.

Invalid Task Life-cycle

In some cases a task may no longer be valid or is no longer relevant.

Sometimes the task it self will be updated to make it relevant, in this case the task follows the "Standard Development Task Life-Cycle".

In these cases the task is "Cancelled" and moved the "done" column.

  1. Assignee identifies the task is invalid, discusses it with the PM/Lead.

  2. PM/Lead will then apply the appropriate "cancel:*" label to the Task.

  3. PM/Lead moves cancelled task to the "done" column.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment