knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(projmgr)
library(dplyr)
dplyr_milestones <- readRDS(system.file("extdata", "dplyr-milestones.rds", package = "projmgr", mustWork = TRUE))
pkg_issues <- readRDS(system.file("extdata", "viz-issues-data.rds", package = "projmgr", mustWork = TRUE))
pkg_issues$url <- ""

projmgr has many different ways to visualize project status. Note that all visualization functions are currently experimental and still have some known challenges. All feedback is welcome on these visualizations or other desired visualizations.

Gantt Charts

For reporting on time-to-completion, viz_gantt() creates one horizontal bar per item (e.g. issue, milestone) and colors issues by length of time open. Items are ordered by start date, which defaults to the data's created_at data but can be altered via the function's parameters. (This is demonstrated in the Events Data vignette.)

Items which are not yet completed are colored in grey since the true time-to-completion value is censored. Additionally, they do not have the terminal half-dot at the end of the bar.

As an example, let's plot all of the milestones in dplyr's GitHub repository, as pulled on January 1, 2019.

viz_gantt(dplyr_milestones)

Note that this plot shows some of the risks of black-box functions. At the time of writing, the "bluesky" milestone was open on GitHub yet has no uncompleted issues. It's important to be precise about your definition of done, or change the start and end parameters to use variables most closely aligned to your definition.

As a ggplot, standard ggplot2 features and styling can be added to the output.

viz_gantt(dplyr_milestones) +
  ggplot2::labs(subtitle = 'Milestones in the dplyr repository')

Task Boards

viz_taskboard() creates an Agile-like taskboard of items (e.g. issues, milestones) to be started, in progress, and completed.

For example, imagine pulling issues from a hypothetical R package into the pkg_issues dataframe.

viz_taskboard(pkg_issues, 
              in_progress_when = is_labeled_with("in-progress"), 
              str_wrap_width = 40)

Users specify what logic to use for identifying "in progress" items by passing a function factory to the in_progress_when parameter. The above example uses the is_labeled_with() option. Other options include:

ls('package:projmgr')[grep("^is_*", ls('package:projmgr'))]

See ?taskboard_helpers for more details.

As a second example, suppose we instead classify issues as in progress once they have been put in a milestone.

viz_taskboard(pkg_issues, 
              in_progress_when = is_in_a_milestone(), 
              str_wrap_width = 40)

Or when they were assigned to "emilyriederer".

viz_taskboard(pkg_issues, 
              in_progress_when = is_assigned_to("emilyriederer"), 
              str_wrap_width = 40)

Unfortunately, this function currently suffers from spacing problems when trying to show many items or items with very long names. Users can corrently attempt to fix this by experimenting with the str_wrap_width and text_size parameters or by adjusting the fig.width and fig.height RMarkdown options; however, in the long-term, this should be handled in a more sustainable, automated fashion.

HTML Task Boards

As an alternative to plot-based taskboards, the report_taskboard() function creates a taskboard built with HTML and CSS.

report_taskboard(pkg_issues, in_progress_when = is_assigned_to("emilyriederer"))

Optional parameters of this function are include_link (whether to link back to the relevant GitHub issue), hover (for slightly enlarging a task on hover), and colors (to provide a character vector of colors to override the defaults.)

report_taskboard(pkg_issues, 
                 in_progress_when = is_assigned_to("emilyriederer"),
                 include_link = FALSE,
                 hover = TRUE,
                 colors = c('#ff0000', '#00ff00', '#0000ff'))

To understand the benefits of report_taskboard() over viz_taskboard()'s reactivity, compare the results on these two outputs as you resize your browser window.

However, note that unlike other report_ functions, report_taskboard()'s reliance on CSS grid means this it will generally not render elegantly within emails (as many major providers do not fully render CSS grid.) Test this before you include it in any emails.

Waterfall Charts

viz_waterfall() creates a waterfall plot showing, for a fixed time-period, the initial open count, newly opened, newly closed, and final open count of issues or milestones.

viz_waterfall(pkg_issues, start_date = '2018-11-20', end_date = '2018-12-15')


emilyriederer/projmgr documentation built on Jan. 26, 2024, 3:09 a.m.