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) APA2) MLA3) 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 ~/.RenvironProvide 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: