Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Write readme #8

Merged
merged 3 commits into from
Oct 30, 2024
Merged

Write readme #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a5bc3fd
add bulk of readme
jenna-a2ai Oct 29, 2024
c8b1ae8
Update README.md
jenna-a2ai Oct 29, 2024
cd8bcee
Update README.md
jenna-a2ai Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 88 additions & 10 deletions README.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ knitr::opts_chunk$set(
[![R-CMD-check](https://github.com/A2-ai/ghqc.app/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/A2-ai/ghqc.app/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of the ghqc ecosystem is to simplify, standardize, and improve traceability of the QC process through the use of shiny apps which create GitHub Issues and Milestones for your project. ghqc.app is intended to be used with the [ghqc](https://github.com/a2-ai/ghqc) package, which will aid in the setup and launching of the shiny apps. The ghqc.app package has 3 main applications/functions:
The goal of the ghqc ecosystem is to simplify, standardize, and improve traceability of the QC process through the use of shiny apps which create GitHub Issues and Milestones for your project. `ghqc.app` is intended to be used with the [ghqc](https://github.com/a2-ai/ghqc) package, which will aid in the setup and launching of the shiny apps. The package has 3 main applications/functions:

1. GHQC_ASSIGN_APP: This app will help you to assign a set of files, checklists, and reviewers to a GitHub Milestone to kick-off the QC process.
1. `ghqc_assign_app`: This app helps the author assign a set of files, each with a corresponding checklist and QCer, to a GitHub Milestone to kick-off the QC review.

2. GHQC_RESOLVE_APP: After each cycle of QC review, this app will help you to communicate your resolution of a comment to the reviewer through file differences
2. `ghqc_resolve_app`: Throughout the QC review, this app helps the author communicate resolution of QC findings through comparison of file differences, hashes, and commits.

3. GHQC_RECORD_APP: At the end of the QC review, this app will help you to create a record, in the form of a pdf, to be saved to show the results of the QC review
3. `ghqc_record_app`: This app generates a record that compiles QC review that occurred on GitHub.

## Installation

Expand All @@ -39,11 +39,89 @@ pak::pak("a2-ai/ghqc.app")

## Interacting with ghqc

## Example

This is a basic example which shows you how to solve a common problem:

```{r example}
``` r
library(ghqc.app)
## basic example code
```

## Assign file(s) for QC

`ghqc_assign_app` 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 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.

## Resolve QC finding(s)

`ghqc_resolve_app` 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 \link{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.

## Generate QC Record

`ghqc_record_app` 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.


141 changes: 127 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,16 @@ intended to be used with the [ghqc](https://github.com/a2-ai/ghqc)
package, which will aid in the setup and launching of the shiny apps.
The ghqc.app package has 3 main applications/functions:

1. GHQC_ASSIGN_APP: This app will help you to assign a set of files,
checklists, and reviewers to a GitHub Milestone to kick-off the QC
process.
1. `ghqc_assign_app`: This app helps the author assign a set of files,
each with a corresponding checklist and QCer, to a GitHub Milestone
to kick-off the QC review.

2. GHQC_RESOLVE_APP: After each cycle of QC review, this app will help
you to communicate your resolution of a comment to the reviewer
through file differences
2. `ghqc_resolve_app`: Throughout the QC review, this app helps the
author communicate resolution of QC findings through comparison of
file differences, hashes, and commits.

3. GHQC_RECORD_APP: At the end of the QC review, this app will help you
to create a record, in the form of a pdf, to be saved to show the
results of the QC review
3. `ghqc_record_app`: This app generates a record that compiles QC
review that occurred on GitHub.

## Installation

Expand All @@ -39,11 +38,125 @@ pak::pak("a2-ai/ghqc.app")

## Interacting with ghqc

## Example

This is a basic example which shows you how to solve a common problem:

``` r
library(ghqc.app)
## basic example code
```

## Assign file(s) for QC

`ghqc_assign_app` 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.

https://github.com/user-attachments/assets/1e796136-681b-4650-88c0-b93a5d680fbc

#### To Assign 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.

## Resolve QC finding(s)

`ghqc_resolve_app` 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()`.

https://github.com/user-attachments/assets/b1583899-8afb-4e42-96f2-7ecd5a9a168b


#### 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.

## Generate QC Record

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




https://github.com/user-attachments/assets/7c3aa961-b3e7-466d-b273-2ef500d10313





#### 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.
Loading