Custom configuration repository

The Custom configuration repository hosts custom options for app inputs and outputs, including an organization’s QC checklist templates.

This git repo is

created and edited by organization administrators.
cloned to an isolated non-project directory by users

See an example configuration repository here: ghqc.example_config_repo .

The configuration repository can be named anything. The naming convention is ghqc.org, where org is the organization name.

The configuration repository https URL is inputted to ghqc via the GHQC_CONFIG_REPO environment variable.
To set this variable, add it to your .Renviron:

GHQC_CONFIG_REPO=https://github.com/A2-ai/ghqc.example_info_repo.git

or input the GHQC_CONFIG_REPO variable during setup.

Repository Structure

The repository must have a folder named “checklists” in the root.
The logo.png and options.yaml are optional.

If the logo.png or options.yaml are included, they must have those names exactly to be recognized by ghqc.

Checklists

Checklists are stored in the “checklists” folder; ghqc accepts both .txt and specific .yaml formats (outlined below).

txt checklists

txt checklists are the most flexible - any contents in .txt files are accepted by ghqc.

The template formats best as GitHub-flavored markdown, with headers beginning at header 2 (##).

The name of the checklist rendered in the app and Issue output is given by the file name: e.g. `Code Review`.txt (use back ticks to include spaces in the checklist template name).

The checklist title and prepended checklist note (if included) will prepend all generated checklists, so including a title in the template is not necessary.

# <Checklist title>

<prepended checklist note (if included)>

<checklist template in GFM>

The easiest way to create .txt checklist templates is to do so in a mock GitHub Issue, where its rendered output can be previewed immediately before pasting into a its corresponding .txt file.

yaml checklists

yaml checklists have one of the following structures:

Simple structure

yaml contents:

General Script:
  - good documentation
  - only relative paths to sourced files
  - consistent style and naming conventions

Output rendered in GitHub Issue:

The simple structure:

begins with the name of the checklist to be displayed in ghqc_assign_app() as the key
the value is a list of checklist items, each of which is prepended with a tick mark on a new line

Header structure

yaml contents:

Report:
  Table of Contents:
    - depth of 2

  Body:
    - Page numbers exist on each page
    - Page numbers indicate total page length (e.g. Page 1 of 3)

  Tables and Figures:
    - Titles are correct
    - Captions are descriptive
    - Footnotes are accurate

  Appendix:
    - |-
      Sources are given in one of the following formats:
        1) APA
        2) MLA
        3) Chicago

Output rendered in GitHub Issue:

The header structure:

begins with the name of the checklist to be displayed in ghqc_assign_app() as the key
the value is a set of headers, which are keys themselves
the value of each header key is a list of checklist items to appear under the header
each checklist item is prepended with a tick mark on a new line

Extra considerations

To include a colon in a checklist item, wrap it in quotation marks.
Example:
```
- "the code is: readable, scalable, and documented"
```
To span a checklist item across multiple lines, begin the first line with the pipe operator, then start the checklist item contents on the next line.
Example:
```
- |-
    Sources are given in one of the following formats:
      1) APA
      2) MLA
      3) Chicago
```

Logo

This file is optional.
If included, it should be named logo.png to be recognized by the package.
The function of this file is to supply an image appear in the header of each page of QC Records generated by ghqc_record_app().
For example, the logo of one’s institution may be used.
If not included, no image will appear in the headers of QC Records generated by ghqc_record_app().

For example, here is the ghqc logo rendered in a QC Record:

Options

This file is optional.
If included, it should be named options.yaml to be recognized by the package.
The function of this file is to supply various user-options to ghqc operations.

Recognized inputs

`prepended_checklist_note`

This option is optionally included.
The function of this option is to prepend checklists rendered to GitHub with a note for users (either the author or QCer). For example, the note may prompt the script author to modify checklist items to make them more specific to the given script.
If not included, no note will appear before generated checklists.

The key is prepended_checklist_note, and the value is the contents of the note.

Example:

prepended_checklist_note: "Note: Please modify checklist items to insert relevant QC context."

Output rendered in GitHub Issue:

`checklist_display_name_var`

This option is optionally included.
The function of this option is to change the display name of the word “checklist” in ghqc_assign_app().
If not included, the word “checklist” will be displayed by default.

The key is checklist_display_name_var, and the value is the name to display in place of the word “checklist”.

Example:

checklist_display_name_var: "QC Assessment List"

Output rendered in ghqc_assign_app():

Repository and checklist validation

To validate that ghqc can parse the repository, run:

library(ghqc)

setup_ghqc_renviron(GHQC_CONFIG_REPO = <repository https URL>)
check_ghqc_configuration()

Alternatively, input the https URL when running ghqc::ghqc_setup():

> ghqc::ghqc_setup()

── GHQC RENVIRON SETUP ───────────────────────────────────────────────────────────────────────────────────────────────

GHQC_CONFIG_REPO is not set in your ~/.Renviron
Provide the URL to the configuring information repository: https://github.com/A2-ai/ghqc.example_info_repo.git
✔ GHQC_CONFIG_REPO was successfully updated to https://github.com/A2-ai/ghqc.example_info_repo.git in ~/.Renviron

── CONFIGURING INFORMATION REPOSITORY ────────────────────────────────────────────────────────────────────────────────

Path to download the configuration information repository (~/.local/share/ghqc/ghqc.example_info_repo)

→ Attempting to clone https://github.com/A2-ai/ghqc.example_info_repo.git to ~/.local/share/ghqc/ghqc.example_info_repo...
✔ Successfully cloned ghqc.example_info_repo to ~/.local/share/ghqc/ghqc.example_info_repo

── ghqc.example_info_repo Local Content ──

✔ logo.png successfully found

✔ 'note' successfully found

    "Note: Please modify checklist items to insert relevant QC context."
    —

✔ Checklist directory successfully found

── Checklist directory content
✔ advanced_checklist.yaml
✔ simple_checklist.yaml

ghqc will indicate if the repository isn’t formatted according to ghqc convention (the only requirement is the checklists directory):

If this directory isn’t present, an error will occur when running ghqc_assign_app():

ghqc will also indicate if checklists aren’t formatted according to its convention: