Demos and examples

See below for examples of each step of the following workflow pattern.

Author creates Milestone

1. The Author pushes final changes to the set of files for QC review.

2. The Author runs the Assign shiny app to:

   • notify the QCer that files assigned to her are ready for review
   • publish each QC file’s corresponding Issue to GitHub, each with a QC checklist and metadata for traceability

   console

   library(ghqc)
   ghqc_assign_app()

3. The Author edits each Issue to revise the QC checklist, insert information into placeholders, and provide necessary context for the QCer.

Example

Here is an example GitHub Milestone created by the Assign app: It has one ghqc Issue, named for the relative path of its corresponding file.

Here is the Issue within this Milestone:

Demo

console

library(ghqc)
ghqc_assign_app()

QCer configures repo and reviews

The QCer:

1. Assigns herself to the Issue if she’s not already assigned

   

2. Clones the repository if necessary

3. Confirms that her local repo is configured for QC with the Status app

   console

   library(ghqc)
   ghqc_status_app()

   She may have to switch branches or pull to get the most the most recent version of the QC file.

   She can confirm she’s reviewing the correct QC file version in her local repo by verifying its Git Status is Up to date in the Status app.

4. Reviews the QC file

5. Checks off items in the Issue body’s QC Checklist

QCer gives feedback

QC review workflows vary between organizations. QCer protocol can range from:

• Providing feedback while leaving code unchanged
• Commenting in-line feedback within the code
• Directly revising code

Providing feedback while leaving code unchanged

Example

QC feedback can be provided by commenting directly in a QC file’s Issue thread.

Tip

With ghqc_status_app() open, the QCer can navigate to the Issue thread quickly.

The QCer can comment on one or more lines of code by copying a permalink from the file contents page in the metadata section.

Demo

Tip

To copy multiple lines: after selecting the first line, hold shift when selecting the last line, then click the three dots to copy the permalink.

Commenting in-line feedback within the code

Example

1. The QCer pushes in-line code comments directly to the Author’s branch.

2. (Optional) The QCer posts a QC Notification for the Author.

   

   Note

   Make a newline for QC comments to avoid merge conflicts with the Author.

   Like this:

   # QC: Change the value of this seed
   seed <- 12345

   Instead of this:

   seed <- 12345 # QC: Change the value of this seed

Demo

console

library(ghqc)
ghqc_status_app()

Author responds

1. If the QCer left in-line code comments, the Author pulls.

2. The Author views QC feedback and follows up if necessary.

3. If file changes are necessary, the Author pushes them to the remote repo.

4. (Optional) The Author posts a QC Notification for the QCer.

Example

The current commit in the metadata section gives the commit with the most up-to-date version of the file.

Demo

console

library(ghqc)
ghqc_status_app()

QCer approves

1. The QCer confirms that no further feedback or file changes are pending.

2. The QCer checks off each item in the QC checklist on the QC file’s Github Issue.

3. The QCer ensures that no in-line code comments are lingering and that the file state is up-to-date with the most recent version from the Author.

4. The QCer approves with ghqc_status_app()

Example

Demo

console

library(ghqc)
ghqc_status_app()

Author generates QC Record

The QC Record is a pdf with the QC history scraped from GitHub for each Issue created with ghqc_assign_app().

It also provides summary tables for an overview of the QC process.

1. The Author closes all relevant Milestones to mark them as completed.

   

2. The Author runs ghqc_status_app() to double-check the status of each Issue in the set of Milestones to ensure completion.

   The author verifies that QC is complete when the QC Status is Approved and the Git Status is Up to date.

3. The Author generates the QC record with ghqc_record_app() (demo below).

4. The Author merges and deletes his branch.

Example

The QC Record begins with a Milestone Summary table.

Each Milestone section contains an Issue Summary table with subsections for each Issue.

Demo

console

library(ghqc)
ghqc_record_app()