Skip to content

Issues Workflow

Jump to bottom Edit New page
Ben Best edited this page Aug 1, 2014 · 44 revisions

Contents

Overview

Issues are a great way of discretizing tasks and managing projects. By creating a private repository "issues" we can freely create and comment issues per Github organization: ohi-science, cmap-ucsb, arctic-options. Note that some organizations, such as ohi-science may have many repositories, some of which are public and some private, so this acts as a way of consolidating issues.

Please peruse Mastering Issues to familiarize yourself with Github's native functionality.

Once the issues are created, they can be organized with a 3rd party Kanban board style of software that sits on top of Github to drag and drop by status (horizontally) and priority (vertically). For this, we'll use Zenhub (see below Prioritize Issues with Zenhub).

Simple-kanban-board

Create Issue

Visit https://github.com/cmap-ucsb/issues/issues (yes, issues in a repo called issues), click New Issue.

Use markdown in the body. This is the quick formatting language also used in RStudio with embeddable chunks of R code, aka Rmarkdown, so it's worth getting to know.

Click Preview to see how it looks before submitting.

You can drag images to upload and embed.

Choose Issue Title

Choose a short title descriptive of the issue. I suggest we use labels to separate project components (see Label Issue). Try using short prefix to indicate any other easily gleaned aspects, like:

  • goal, eg Livelihoods & Economies "LE: update trend function with detailed layers"

Reference Issue in a Commit Message

Previously issues were entered in ohi-science/ohicore. Commit messages from within that repo could simply include "#164" to link the commit with issue 164 and even "closes #164" to close that issue. For commits from a different repo, say ohiprep, you need to spell out the full organization/repo in order to make the linkage such as "ohi-science/ohicore#164" or " fixes ohi-science/ohicore#164". You can similarly link any commit with an issue by including a message like "cmap-ucsb/issues#1".

You can enter these commit messages directly from RStudio. See ohi-science/ohiprep:wiki/Setup#rstudio.

For more details:

Comment on Issue

When you comment on an issue you can directly notify another user, eg "@jules32", which sends an email having the comment and link to the issue to that Github user's registered email. To reach every member of the cmap-ucsb Issues team, use "@cmap-ucsb/issues".

Label Issue

We could start with these:

  • component, (shades of blue) eg for OHI-Science roughly corresponding to other repos:
    • c:core
    • c:gui
    • c:prep
  • document, (shades of green) eg for OHI-Science roughly corresponding to other repos:
    • d:manual
    • d:manuscript
    • d:report
    • d:web
  • type (shades of orange)
    • t:bug
    • t:feature
    • t:task

The specific status and urgency of the open issues can be handled by Zenhub (see below Prioritize Issues with Zenhub).

For more examples, see How to manage github issues for (priority, etc)? - stackexchange.com.

Assign Issue to Milestone

You can associate an issue with a deadline using Milestones. Previously named milestones per weekly lab meeting with overarching goals to accomplish by then, eg "2014-06-09: tbx fxns", 2014-06-16: gl2014", "2014-06-23: gl2013, tbx". As issues within the milestone get closed the percent completed bar grows.

A previous view from BB for BH with Huboard showed issues by Milestone, which was a handy overview, but the priorization (ie vertical position) had to be handled manually with ugly hidden code (see ohiprep:Using GitHub). In fact the better, more appropriate use for the Kanban board is using the horizontal arrangement by Status (see below Prioritize Issues with Zenhub). But I did suggest this feature to Zenhub in issue #103: swap Milestones for Pipelines: view to prioritize issues across Milestones, which they sound amenable to.

Prioritize Issues with Zenhub

You'll need to use the Google Chrome browser and install the Zenhub.io extension.

Once installed, you'll notice a "||| Boards" right-hand navigation item in the repo (below "<> Code", above "! Issues"). The first time you click on this, it will ask you for authorization using your Github password. If the repo doesn't have a board yet, you'll be asked to select a board type with different default "pipelines" which are the drag-n-drop slots for differentiating the Status of an issue horizontally and prioritizing vertically. I suggest the following pipelines for open issues:

  • todo: default initial pipeline, so not yet queued for discussion or otherwise ready to work on
  • discuss: need to discuss before ready
  • ready: ready to be worked on
  • doing: in progress
  • later: pushing off to later

Zenhub allows you to filter by Labels, Milestones and Assignees (ie the user assigned to complete the issue). You can filter for instance, for just your own issues and a given label. Then you can drag and drop issues between pipeline Status with higher Priority towards the top. Urgent tasks would be at the very top. This drag and drop prioritization on a board comes from the concept of a Kanban board.

For more on how to use Zenhub, check out Zenhub features.

More Guidance

Other Tools

Not currently using any of these, but might prove useful down the road:

Add a custom footer
Add a custom sidebar

Clone this wiki locally