Package 'ghqc'

Title: Manage QC via GitHub Issues using Shiny Apps
Description: This package launches 3 ghqc applications as background jobs to aid the QC process through the use of shiny apps. It also contains aides to maintain the proper setup of the ecosystem. Namely, it will aid in the installation of ghqc.app and its dependendencies into an isolated directory as to not interfere with the project being QCed.
Authors: Anne Zheng [aut], Jenna Johnson [aut], Janelle Lennie [ctb], Devin Pastoor [aut], Wes Cummings [aut, cre]
Maintainer: Wes Cummings <[email protected]>
License: GPL (>= 3) + file LICENSE
Version: 0.2.0
Built: 2024-11-22 17:23:37 UTC
Source: https://github.com/a2-ai/ghqc

Help Index

Check the content of the downloaded ghqc custom configuration repository and download any updates needed

Description

Check the content of the downloaded ghqc custom configuration repository and download any updates needed

Usage

check_ghqc_configuration(config_path = ghqc_config_path())

Arguments

config_path

(optional) path in which the repository, set in environmental variable GHQC_CONFIG_REPO, is, or should be, downloaded to. Defaults to ⁠~/.local/share/ghqc/{repo_name}⁠

Check the installed/linked packages in lib_path against the recommended ghqc.app dependency package version

Description

Check the installed/linked packages in lib_path against the recommended ghqc.app dependency package version

Usage

check_ghqcapp_dependencies(lib_path = ghqc_libpath(), use_pak = TRUE)

Arguments

lib_path

(optional) the path to the installed/linked dependencies. If not set, defaults to "~/.local/share/ghqc/rpkgs"
use_pak

(optional) optionally removes the requirement to have pak installed in the project repository. Setting to FALSE will reduce performance

Value

This function is primarily used for its printed results and subsequent actions, not a returned output. Will return a dataframe of package upgrades needed

Download the custom configuration repository as set in environmental variable GHQC_CONFIG_REPO

Description

Download the custom configuration repository as set in environmental variable GHQC_CONFIG_REPO

Usage

download_ghqc_configuration(config_path = ghqc_config_path(), .force = FALSE)

Arguments

config_path

(optional) path in which the repository, set in environmental variable GHQC_CONFIG_REPO, is, or should be, downloaded to. Defaults to ⁠~/.local/share/ghqc/{repo_name}⁠
.force

(optional) option to force a new download of the ghqc custom configuration repository

Assign file(s) to be reviewed for QC

Description

This function provides an interface to assign one or more files for QC in the form of a GitHub Issue(s) within a GitHub Milestone, with options to assign a repository collaborator as the QCer and/or generate a checklist of suggested review tasks during QC.

Each Issue created corresponds to a single file assigned to be reviewed for QC. Issues are organized into Milestones as designated by the user.

To assign file(s) for QC:

  1. Input a name to create a new Milestone or select an existing Milestone.

  2. Optional: if creating a new Milestone, input a description.

  3. Optional: select one or more collaborators who will be assigned to perform the QC. The selected collaborator(s) will not be assignee(s) until explicitly assigned to one or more selected files (Step 5 below).

  4. Select one or more files from the file tree. Click the + signs to expand directories in the file tree.

  5. Optional: select an assignee for each selected file.

  6. Select a checklist type for each selected file.

  7. Post the Milestone by clicking "Assign File(s) for QC" on the bottom of the pane.

At any time, the user can:

  • Click the ⁠Preview file contents⁠ button below a selected file to view its contents.

  • Click the ⁠Preview checklist⁠ button below a selected file to view the items in a its selected checklist.

Usage

ghqc_assign_app(
  app_name = "ghqc_assign_app",
  qc_dir = getwd(),
  lib_path = ghqc_libpath(),
  config_path = ghqc_config_path()
)

Arguments

app_name

the name of the app to run in the background
qc_dir

the directory in which the app is run
lib_path

the path to the ghqc package and its dependencies
config_path

the path to the ghqc configuring information

See Also

ghqc_resolve_app and ghqc_record_app

The default install location for the ghqc custom configuration repository

Description

The default install location for the ghqc custom configuration repository

Usage

ghqc_config_path()

Value

string containing the default path to the ghqc custom configuration repository (~/.local/share/ghqc/<config repo name here>

The default install location for the ghqc package and its dependencies. If it does not exist, it will be created.

Description

The default install location for the ghqc package and its dependencies. If it does not exist, it will be created.

Usage

ghqc_libpath()

Value

string containing the default lib path for the ghqc package and its dependencies (~/.local/share/ghqc/rpkgs)

Generate a QC Record for one or more Milestones

Description

This function allows the user to generate a QC Record for one or more Milestones created with ghqc_assign_app.

To Generate a QC Record:

  1. Select one or more Milestones.

    • optional to include both open and closed Milestones by unchecking "Closed Milestones only".

  2. Optional: input a name for the PDF.

    • The default name is a hyphenated combination of the GitHub repository name and selected Milestone name(s).

  3. Optional: input the directory in which to generate the PDF.

    • The default directory is the root of the R project.

  4. Optional: indicate if the report should only include the Milestone and Issue summary tables by checking "Just tables". Else, the default setting will generate a Record that contains the summary tables up front as well as detailed descriptions for each Issue including version control information, users, datetimes, events, actions, comments and more.

  5. Create the PDF by clicking "Generate QC Record" at the bottom of the pane.

Usage

ghqc_record_app(
  app_name = "ghqc_record_app",
  qc_dir = getwd(),
  lib_path = ghqc_libpath(),
  config_path = ghqc_config_path()
)

Arguments

app_name

the name of the app to run in the background
qc_dir

the directory in which the app is run
lib_path

the path to the ghqc package and its dependencies
config_path

the path to the ghqc configuring information

See Also

ghqc_assign_app and ghqc_resolve_app

Comment in an Issue to display file changes during QC

Description

This function allows a user to insert a comment into a ghqc GitHub Issue that displays changes in the version control information for the Issue’s corresponding file. By default, the comment displays both the original and current commits and hashes for the file. These versions are selected by the user. The comment can optionally display the file difference (“diff”) between the current and previous versions. These changes will likely be implementations of QC feedback.

To use this app, first initialize one or more Issues with ghqc_assign_app.

To comment in an Issue:

  1. Optional: filter to the set of Issues within a Milestone.

  2. Select the Issue to be updated.

  3. Optional: provide a contextualizing message about the changes made to the file (e.g. “Implemented QC feedback for line 20”).

  4. Optional: insert the file difference display into the comment, by selecting “Show file difference”. If displaying the file difference, choose to either:

    • compare the original version with the current version or,

    • compare a previous version with the current version.

  5. Optional: preview the comment before posting to the Issue.

  6. Post the comment to the Issue.

Usage

ghqc_resolve_app(
  app_name = "ghqc_resolve_app",
  qc_dir = getwd(),
  lib_path = ghqc_libpath(),
  config_path = ghqc_config_path()
)

Arguments

app_name

the name of the app to run in the background
qc_dir

the directory in which the app is run
lib_path

the path to the ghqc package and its dependencies
config_path

the path to the ghqc configuring information

See Also

ghqc_assign_app and ghqc_record_app

Situation report for ghqc set-up

Description

Situation report for ghqc set-up

Usage

ghqc_sitrep(..., lib_path = ghqc_libpath(), config_path = ghqc_config_path())

Arguments

...

options to expand output. Current option is only "pkgs" to expand list of dependencies
lib_path

the path to the ghqc package and its dependencies
config_path

the path to the ghqc custom configuration

Value

This function is primarily used for its printed output, not a returned output

install ghqc.app's dependencies into an isolated library

Description

install ghqc.app's dependencies into an isolated library

Usage

install_ghqcapp_dependencies(
  lib_path = ghqc_libpath(),
  pkgs = ghqc_depends,
  use_pak = TRUE
)

Arguments

lib_path

(optional) the path to install the dependencies. If not set, defaults to "~/.local/share/ghqc/rpkgs"
pkgs

(optional) list of packages to install. Defaults to ghqc and all of its dependencies
use_pak

(optional) optionally removes the requirement to have pak installed in the project repository. Setting to FALSE will reduce performance

Shiny is "ready" if the download.file is able to serve the starting html, at this point, we will try to hit the shiny app and see if it downloads

Description

Shiny is "ready" if the download.file is able to serve the starting html, at this point, we will try to hit the shiny app and see if it downloads

Usage

is_shiny_ready(url)

Arguments

url

the http port

Value

true or false depending on if Shiny is ready

symlink previously installed package library containing all ghqc.app dependencies to an isolated package library

Description

symlink previously installed package library containing all ghqc.app dependencies to an isolated package library

Usage

link_ghqcapp_dependencies(link_path, lib_path = ghqc_libpath())

Arguments

link_path

the path to the installed package library
lib_path

(optional) the path to install the dependencies. If not set, defaults to "~/.local/share/ghqc/rpkgs"

Value

this function is primarly used for its effects, but will the results of the symlink

Remove the downloaded custom configuration repository from config_path

Description

Remove the downloaded custom configuration repository from config_path

Usage

remove_ghqc_configuration(config_path = ghqc_config_path())

Arguments

config_path

(optional) path in which the repository, set in environmental variable GHQC_CONFIG_REPO, is, or should be, downloaded to. Defaults to ⁠~/.local/share/ghqc/{repo_name}⁠

Value

this function is used for its effects, but will return the removed config_path

Remove all content in the specified lib path. Optionally removes the cache as well.

Description

Remove all content in the specified lib path. Optionally removes the cache as well.

Usage

remove_ghqc_dependencies(lib_path = ghqc_libpath(), cache = FALSE)

Arguments

lib_path

(optional) the path to the installed dependency packages. If not set, defaults to "~/.local/share/ghqc/rpkgs"
cache

(optional) flag of whether to clear the cache or not. Defaults to keeping the cache

Value

information related to deleted lib path

Interactive function to set up the ghqc environment, including writing to the .Renviron, custom configuration repository download, and ghqc.app dependency installation/linking, for use of the ghqc application suite

Description

Interactive function to set up the ghqc environment, including writing to the .Renviron, custom configuration repository download, and ghqc.app dependency installation/linking, for use of the ghqc application suite

Usage

setup_ghqc()

Value

This function is used for its effects, not outputs. It will return the results of any ghqc dependency installation as needed

helper function to setup/write Renviron file for ghqc

Description

helper function to setup/write Renviron file for ghqc

Usage

setup_ghqc_renviron(GHQC_CONFIG_REPO)

Arguments

GHQC_CONFIG_REPO

Repository URL to the custom configuration repository

Value

This function is used primarly to write to the ~/.Renviron file. It will return the text contained in ~/.Renviron