qcthat

{qcthat} is a quality control framework for R packages. It has been developed for use in the gsm family of packages, such as gsm.core.

The goal of {qcthat} is to produce qualification reports linking GitHub issues to evidence that those issues have been implemented. These reports can be used as part of a quality control and acceptance process for R packages, particularly those used in regulated environments such as clinical trials.

⚙️ Installation

You can install the latest release of qcthat from GitHub with:

# install.packages("pak")
pak::pak("Gilead-BioStats/qcthat@*release")

You can install the development version of qcthat from GitHub with:

# install.packages("pak")
pak::pak("Gilead-BioStats/qcthat")

Learn more in vignette("qcthat").

📋 Example Report Process

Action_qcthat() installs a GitHub action to generate QC reports. At its core, it uses the functions QCPackage(), QCPR(), QCCompletedIssues(), and QCMilestones() to generate a report like this:

✅ A qcthat issue test matrix with 1 milestone, 19 issues, and 59 tests

└─█─Milestone: v1.0.0 (19 issues, 59 tests)
  ├─☑️─Technical Task 101: Switch `lglShowIgnoredLabels` default to TRUE
  │ └─✅─Ignored issues are shown by default (#101)
  ├─☑️─Feature 80: Filter main qcthat report to only "closed (completed)"
  │ └─✅─QCCompletedIssues filters to completed issues (#80, #69)
  ├─☑️─Bug 77: GHA-generated report stability
  │ └─✅─Reports generated via GHA include information about the issues (#77, #37)
  ├─☑️─Feature 73: Add qcthis.yaml to a package
  │ ├─✅─InstallAction calls InstallFile with expected parts (#73)
  │ ├─✅─Action_qcthat targets the expected action (#55, #68, #69, #73, #88, #141, #157, #198)
  │ ├─✅─qcthatPath constructs paths (#73)
  │ └─✅─InstallFile copies files as expected (#73)
  ├─☑️─Technical Task 72: Add qc report to triggering PR as comment
  │ └─✅─CommentReport generates the expected call (#99, #72)
  ├─☑️─Requirement 69: Package QC Report Usability
  │ ├─✅─Action_qcthat targets the expected action (#55, #68, #69, #73, #88, #141, #157, #198)
  │ ├─✅─Can print without milestone info (#40, #69)
  │ ├─✅─QCPackage wraps the core qcthat functions (#46, #69)
  │ └─✅─QCCompletedIssues filters to completed issues (#80, #69)
  ├─☑️─Requirement 68: PR/Branch Report
  │ ├─✅─Action_qcthat targets the expected action (#55, #68, #69, #73, #88, #141, #157, #198)
  │ ├─✅─QCMergeGH filters to merge-associated issues (#68, #84)
  │ ├─✅─QCMergeLocal filters to ref-specific issues (#68, #84)
  │ ├─✅─QCPR filters to PR-related issues (#68, #84)
  │ └─✅─QCMilestones reports on specific milestones (#88, #68)
  ├─☑️─Feature 67: Ignore issues with `qcthat-nocov` label
  │ ├─✅─CompileIssueTestMatrix excludes issues in chrIgnoredLabels (#67)
  │ ├─✅─ExtractDisposition() helper counts test errors as failures (#67)
  │ └─✅─Can report ignored issue counts (#67, #81)
  ├─☑️─Feature 55: GHA: Report of associated issues
  │ └─✅─Action_qcthat targets the expected action (#55, #68, #69, #73, #88, #141, #157, #198)
  ├─☑️─Feature 46: Wrapper to run everything
  │ └─✅─QCPackage wraps the core qcthat functions (#46, #69)
  ├─☑️─Feature 40: Print Without Milestones
  │ └─✅─Can print without milestone info (#40, #69)
  ├─☑️─Bug 96: Don't include ignored labels in `QCIssues()` warnings
  │ └─✅─QCIssues doesn't warn about ignored issues (#96)
  ├─☑️─Bug 95: Install qcthat as part of Action installation
  │ └─✅─qcthat is installed as part of the GHA (#95)
  ├─☑️─Feature 90: Function to create qcthat-nocov label
  │ ├─✅─CreateGHLabel reports success conditional on lglVerbose (#90)
  │ ├─✅─CreateGHLabel throws an error if the API doesn't report the expected result (#90)
  │ ├─✅─CreateGHLabel attempts to update existing label (#90)
  │ ├─✅─MaybeUpdateGHLabel decides based on lglUpdate (#90)
  │ ├─✅─UpdateGHLabel makes the expected call (#90)
  │ ├─✅─UpdateGHLabel throws an error if the API doesn't report the expected result (#90)
  │ ├─✅─EmptyLabelsDF returns the expected structure (#90)
  │ ├─✅─EnframeGHLabels returns NULL for empty list (#90)
  │ ├─✅─EnframeGHLabels converts raw labels to data frame (#90)
  │ ├─✅─EnframeGHLabels adds hash to color codes (#90)
  │ ├─✅─FetchGHLabelsRaw calls the correct API endpoint (#90)
  │ ├─✅─FetchGHLabels returns empty data frame when no labels exist (#90)
  │ ├─✅─FetchGHLabels returns data frame with labels (#90)
  │ ├─✅─Default helpers return expected values (#90)
  │ ├─✅─SetupGHLabels creates missing labels (#90)
  │ ├─✅─PrepareDFLabels normalizes correctly (#90)
  │ ├─✅─Helper functions normalize strings correctly (#90)
  │ └─✅─ValidateDFLabels checks for required columns (#90)
  ├─☑️─Feature 88: Report by Milestone
  │ ├─✅─Action_qcthat targets the expected action (#55, #68, #69, #73, #88, #141, #157, #198)
  │ ├─✅─QCMilestones reports on specific milestones (#88, #68)
  │ ├─✅─QCMilestones warns about unknown milestones (#88)
  │ └─✅─QCMilestones errors with no valid milestones (#88)
  ├─☑️─Feature 86: Function to report on specific issues
  │ ├─✅─QCIssues reports on specific issues (#86)
  │ ├─✅─QCIssues warns about unknown issues (#86)
  │ └─✅─QCIssues errors with no valid issues (#86)
  ├─☑️─Feature 85: Report Issue-Test Coverage in Footer
  │ ├─✅─Printing an IssueTestMatrix outputs a user-friendly tree (#31, #36, #60, #85)
  │ └─✅─MakeITRCoverageFooter deals with all cases (#85)
  ├─☑️─Feature 84: Function(s) to filter report to issues associated with PR/branch
  │ ├─✅─FetchMergeCommitSHAs returns unique, sorted SHAs (#84, #133)
  │ ├─✅─FetchAllMergePRNumbers returns unique, sorted PR numbers (#84)
  │ ├─✅─FetchAllMergePRNumbers returns empty vector for no matching PRs (#84)
  │ ├─✅─FetchPRRefs returns source and target refs (#84, #133, #149)
  │ ├─✅─FetchRepoPRs returns an empty df when no issues found (#84)
  │ ├─✅─FetchRepoPRs returns a formatted df for real PRs (#84)
  │ ├─✅─GuessPRNumber delegates to its sub-functions (#84)
  │ ├─✅─GetGHAPRNumber returns NULL for bad arg (#84, #163)
  │ ├─✅─GetGHAPRNumber extracts PR number from lGHEventPayload when available (#84, #163)
  │ ├─✅─GetGHAPRNumber returns NULL for bad extracted PR number (#84, #163)
  │ ├─✅─FetchRefPRNumber fetches PR number for a branch (#84, #132)
  │ ├─✅─QCMergeGH filters to merge-associated issues (#68, #84)
  │ ├─✅─QCMergeLocal filters to ref-specific issues (#68, #84)
  │ ├─✅─FindKeywordIssues extracts issues that will be closed by commits (#84)
  │ ├─✅─QCPR errors informatively for bad intPRNumber (#84)
  │ ├─✅─QCPR filters to PR-related issues (#68, #84)
  │ ├─✅─PrepareGQLQuery constructs a query (#84)
  │ └─✅─GQLWrapper wraps a query correctly (#84)
  └─☑️─Requirement 81: Report issue test coverage
    └─✅─Can report ignored issue counts (#67, #81)
# Issue state: 📥 = open, ☑️ = closed (completed), ⛔ = closed (won't fix)
# Test disposition: ✅ = passed, ❌ = failed, 🚫 = skipped

✅ All tests passed

🟢 All issues have at least one test

🙈 2 issues with label “qcthat-nocov” were ignored

🙋 Contributing

Contributions are welcome! Creating a utility package that is generalizable and extensible to all sorts of repository structures is challenging, and your input is greatly appreciated.

Before submitting a pull request, make sure to file an issue, which should generally fall under one of the following categories:

• Bugfix: something is broken.
• Feature: something is wanted or needed.
• QC: documentation or metadata is incorrect or missing.

New code should generally follow the tidyverse style guide.

Code of Conduct

Please note that the {qcthat} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.