From cfee09d4c53e99235a8e754b3e92123e1227d7b0 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Thu, 22 Aug 2024 00:23:44 -0400 Subject: [PATCH 01/35] Copy checklists directly into pull_request_template.md --- inst/templates/pull_request_template.md | 64 ++++++++++++++++++++----- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 178ed241..4e29634a 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -1,21 +1,59 @@ - - ## Description - - ## Checklist - +Use one of the following checklists depending on which type of PR you are +doing. + +### Peer writing review: see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md + +- [ ] There are no Markdown/pandoc/Latex errors + - [ ] No broken references (?? or ???) in the text (Use find: “??”) + - [ ] There are no blank pages + - [ ] Page x out of y is correct (sometimes y is wrong) + +- [ ] The report adheres to the writing style guide (see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) + - [ ] Text is spell-checked (including captions and footnotes) + - [ ] The correct tense is used throughout the report + - [ ] Capitalization is correct and consistent + - [ ] Acronyms are introduced the first time they're used within a major section + - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) + +- [ ] The writing, including figure and table captions, follow the VISC writing guidelines + - [ ] Objectives follow the SAP and study protocol + - [ ] Results and summary sections map to the objectives + - [ ] Figure and tables are sorted in parallel with results + - [ ] Figure and table references, significance highlighting, and results listed in the text are correct and support my statements + +- [ ] Figures follow the figure guidelines (see see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) + - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure + - [ ] Text is not cut off (facet labels, legends, titles) + +- [ ] All source files are pushed to the repo and the report compiles without errors + - [ ] Unrealated or unnescessary files aren't included (e.g. Latex .toc files) + - [ ] I've opened and checked compiled documents (.pdf, .docx) + +- [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages + +### Code review: see https://github.com/FredHutch/VISC-Documentation/blob/master/Programming/code-review-guideline.md + +- [ ] Necessary context for the analysis is given +- [ ] R Markdown file compiles (or the R code runs) correctly with no errors +- [ ] Code is readable and easy to understand + - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/master/Programming/Coding-Principles.md) document + - [ ] Joins are correct + - [ ] Any filtering is correct and in a logical order + - [ ] Supporting commentary is helpful and does not include debt or backup comments +- [ ] Functions are properly documented +- [ ] The analysis code follows the statistical methods section +- [ ] VISCtemplates and VISCfunctions are used whenever possible +- [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) +- Time estimate: ___________ From 86754f1b20fed04e37087ed98dd5a3900e99eed3 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Thu, 22 Aug 2024 00:25:23 -0400 Subject: [PATCH 02/35] change master to main --- inst/templates/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 4e29634a..700cb788 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -43,12 +43,12 @@ doing. - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages -### Code review: see https://github.com/FredHutch/VISC-Documentation/blob/master/Programming/code-review-guideline.md +### Code review: see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md - [ ] Necessary context for the analysis is given - [ ] R Markdown file compiles (or the R code runs) correctly with no errors - [ ] Code is readable and easy to understand - - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/master/Programming/Coding-Principles.md) document + - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - [ ] Joins are correct - [ ] Any filtering is correct and in a logical order - [ ] Supporting commentary is helpful and does not include debt or backup comments From bd1966c5f4d023fb84a9315901d1eb9aaa0a9708 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:29:59 -0400 Subject: [PATCH 03/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 61 +++++++++++++++++-------- 1 file changed, 42 insertions(+), 19 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 700cb788..f2ef7ba8 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -8,47 +8,70 @@ Give a short background on the report, outline important questions or details fo It's helpful to add links to the key files with the unique ID for the commit (a.k.a. the "SHA" or "hash"). +## Reflection + +Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any GitHub issues in the VISCtemplates or VISCfunctions repos been created that would help for future projects? + ## Checklist -Use one of the following checklists depending on which type of PR you are -doing. +Use one (or multiple) of the following checklists depending on which type of PR you are doing. -### Peer writing review: see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md +### Peer writing review + +See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md + +- [ ] All necessary source files are pushed to the repo and the report has been compiled without errors + - [ ] Unrelated or unnescessary files aren't included (e.g. Latex .toc files) + - [ ] I've opened and checked compiled documents (.pdf, .docx) - [ ] There are no Markdown/pandoc/Latex errors - [ ] No broken references (?? or ???) in the text (Use find: “??”) - [ ] There are no blank pages - [ ] Page x out of y is correct (sometimes y is wrong) - -- [ ] The report adheres to the writing style guide (see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) - - [ ] Text is spell-checked (including captions and footnotes) - - [ ] The correct tense is used throughout the report - - [ ] Capitalization is correct and consistent - - [ ] Acronyms are introduced the first time they're used within a major section + +- [ ] Appropriate versions of R packages are used + - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages + - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used + - [ ] If renv is used, I have run `renv::status()` and resolved any issues + +- [ ] The report text, including figure and table captions, follows the VISC writing guidelines (see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - -- [ ] The writing, including figure and table captions, follow the VISC writing guidelines - [ ] Objectives follow the SAP and study protocol - [ ] Results and summary sections map to the objectives - - [ ] Figure and tables are sorted in parallel with results - - [ ] Figure and table references, significance highlighting, and results listed in the text are correct and support my statements + - [ ] Text is spell-checked (including captions and footnotes) + - [ ] The correct tense is used throughout the report + - [ ] Capitalization is correct and consistent + - [ ] Acronyms are introduced the first time they're used within a major section -- [ ] Figures follow the figure guidelines (see see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) +- [ ] I have reviewed the Results section + - [ ] Figures and tables are sorted in parallel with results, and figure and table references are correct + - [ ] Results listed in the text are correct and support my statements + - [ ] Variables are used in referring to numeric values in the results section (to minimize human error) + +- [ ] Figures look right and follow the figure guidelines (see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure - [ ] Text is not cut off (facet labels, legends, titles) -- [ ] All source files are pushed to the repo and the report compiles without errors - - [ ] Unrealated or unnescessary files aren't included (e.g. Latex .toc files) - - [ ] I've opened and checked compiled documents (.pdf, .docx) +- [ ] Tables look right + - [ ] Text is not running off the page + - [ ] Significance highlighting is as expected -- [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages +### Code review -### Code review: see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md +See https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md - [ ] Necessary context for the analysis is given - [ ] R Markdown file compiles (or the R code runs) correctly with no errors - [ ] Code is readable and easy to understand - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document + - [ ] Lines are at most 100 characters long + - [ ] Consistent use of `<-` not `=` for assignment + - [ ] Object names include only alphanumeric characters and underscores (no dots) + - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) + - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) + - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) + - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput + - [ ] Hard coding and magic numbers are avoided - [ ] Joins are correct - [ ] Any filtering is correct and in a logical order - [ ] Supporting commentary is helpful and does not include debt or backup comments From 087ca04963614e7e34f0b11f40795177b47f4cd6 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:31:19 -0400 Subject: [PATCH 04/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index f2ef7ba8..02f00486 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -16,7 +16,7 @@ Describe any key challenges you faced in working on these changes. Were these ch Use one (or multiple) of the following checklists depending on which type of PR you are doing. -### Peer writing review +### PT report / peer writing review See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md From 89b66b719de5b372f1d473c2021908ff760661d9 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:32:35 -0400 Subject: [PATCH 05/35] switch order of code review and writing review --- inst/templates/pull_request_template.md | 50 ++++++++++++------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 02f00486..db907f68 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -16,6 +16,31 @@ Describe any key challenges you faced in working on these changes. Were these ch Use one (or multiple) of the following checklists depending on which type of PR you are doing. +### Code review + +See https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md + +- [ ] Necessary context for the analysis is given +- [ ] R Markdown file compiles (or the R code runs) correctly with no errors +- [ ] Code is readable and easy to understand + - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document + - [ ] Lines are at most 100 characters long + - [ ] Consistent use of `<-` not `=` for assignment + - [ ] Object names include only alphanumeric characters and underscores (no dots) + - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) + - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) + - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) + - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput + - [ ] Hard coding and magic numbers are avoided + - [ ] Joins are correct + - [ ] Any filtering is correct and in a logical order + - [ ] Supporting commentary is helpful and does not include debt or backup comments +- [ ] Functions are properly documented +- [ ] The analysis code follows the statistical methods section +- [ ] VISCtemplates and VISCfunctions are used whenever possible +- [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) +- Time estimate: ___________ + ### PT report / peer writing review See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md @@ -55,28 +80,3 @@ See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/ - [ ] Tables look right - [ ] Text is not running off the page - [ ] Significance highlighting is as expected - -### Code review - -See https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md - -- [ ] Necessary context for the analysis is given -- [ ] R Markdown file compiles (or the R code runs) correctly with no errors -- [ ] Code is readable and easy to understand - - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - - [ ] Lines are at most 100 characters long - - [ ] Consistent use of `<-` not `=` for assignment - - [ ] Object names include only alphanumeric characters and underscores (no dots) - - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) - - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) - - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - - [ ] Hard coding and magic numbers are avoided - - [ ] Joins are correct - - [ ] Any filtering is correct and in a logical order - - [ ] Supporting commentary is helpful and does not include debt or backup comments -- [ ] Functions are properly documented -- [ ] The analysis code follows the statistical methods section -- [ ] VISCtemplates and VISCfunctions are used whenever possible -- [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) -- Time estimate: ___________ From f4157f3ff2b3c87e67edd47c2398e59eb652764c Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:34:38 -0400 Subject: [PATCH 06/35] add documentation section --- inst/templates/pull_request_template.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index db907f68..03601d3b 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -16,6 +16,10 @@ Describe any key challenges you faced in working on these changes. Were these ch Use one (or multiple) of the following checklists depending on which type of PR you are doing. +### Documentation + +- [ ] Appropriate README.md files have been updated + ### Code review See https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md From f2c4a0da1a6439127d0a2ea6bef3a330a67ff792 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:36:32 -0400 Subject: [PATCH 07/35] add note about when/who to complete checklist --- inst/templates/pull_request_template.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 03601d3b..d43bd342 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -12,9 +12,11 @@ It's helpful to add links to the key files with the unique ID for the commit (a. Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any GitHub issues in the VISCtemplates or VISCfunctions repos been created that would help for future projects? -## Checklist +## Checklist(s) -Use one (or multiple) of the following checklists depending on which type of PR you are doing. +Use one (or multiple) of the following checklists, depending on which type of PR you are doing. + +Checklists should be completed before a pull request is submitted for review. Note: you can create a draft pull request before completing the checklist, then complete the checklist, and then mark the PR as ready for review. ### Documentation From 0038164643d56db10468b9f5a0dc2857a9f74a4e Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:38:02 -0400 Subject: [PATCH 08/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index d43bd342..d90c5c49 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -3,11 +3,11 @@ Make sure to provide a general summary of your changes in the pull request title. Here, describe your changes in detail. - Give a short background on the report, outline important questions or details for the reviewer, and add links to any supporting documents (e.g., protocol presentation). - It's helpful to add links to the key files with the unique ID for the commit (a.k.a. the "SHA" or "hash"). +Make sure to include any known issues in your description. + ## Reflection Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any GitHub issues in the VISCtemplates or VISCfunctions repos been created that would help for future projects? From 0f5f92aa63c0e82806bb7b629c9fac7ad507d68e Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:41:22 -0400 Subject: [PATCH 09/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index d90c5c49..dc4395e7 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -1,12 +1,12 @@ ## Description -Make sure to provide a general summary of your changes in the pull request title. +Make sure to provide a brief summary of your changes in the pull request title above. Here, describe your changes in detail. Give a short background on the report, outline important questions or details for the reviewer, and add links to any supporting documents (e.g., protocol presentation). It's helpful to add links to the key files with the unique ID for the commit (a.k.a. the "SHA" or "hash"). -Make sure to include any known issues in your description. +Make sure to include any known issues as well. ## Reflection @@ -86,3 +86,10 @@ See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/ - [ ] Tables look right - [ ] Text is not running off the page - [ ] Significance highlighting is as expected + +### Explanation for why any boxes above are NOT checked + +If necessary, provide explanations here for why any boxes above are not checked. + +- Reason 1 +- Reason 2 From 3aee6eed2e1fa3d6fe24b7c6a132b93591e24bc3 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:48:00 -0400 Subject: [PATCH 10/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 42 ++++++++++++------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index dc4395e7..8e66a166 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -18,38 +18,38 @@ Use one (or multiple) of the following checklists, depending on which type of PR Checklists should be completed before a pull request is submitted for review. Note: you can create a draft pull request before completing the checklist, then complete the checklist, and then mark the PR as ready for review. -### Documentation +### Documentation (use for all PRs) - [ ] Appropriate README.md files have been updated - -### Code review - -See https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md - -- [ ] Necessary context for the analysis is given -- [ ] R Markdown file compiles (or the R code runs) correctly with no errors -- [ ] Code is readable and easy to understand - - [ ] Code follows the [Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - - [ ] Lines are at most 100 characters long - - [ ] Consistent use of `<-` not `=` for assignment - - [ ] Object names include only alphanumeric characters and underscores (no dots) - - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) - - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) - - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - - [ ] Hard coding and magic numbers are avoided +- [ ] Necessary context for the analysis is given + +### Code review (use for + +See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) + +- [ ] I have compiled the R Markdown file(s) (or run the full R code) with no errors +- [ ] Code is readable and easy to understand, and follows the [VISC Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document + - [ ] Lines are at most 100 characters long + - [ ] Consistent use of `<-` not `=` for assignment + - [ ] Object names include only alphanumeric characters and underscores (no dots) + - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) + - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) + - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) + - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput + - [ ] Hard coding and magic numbers are avoided + - [ ] Supporting commentary is helpful and does not include debt or backup comments +- [ ] Code is logically correct - [ ] Joins are correct - [ ] Any filtering is correct and in a logical order - - [ ] Supporting commentary is helpful and does not include debt or backup comments - [ ] Functions are properly documented - [ ] The analysis code follows the statistical methods section - [ ] VISCtemplates and VISCfunctions are used whenever possible - [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) - Time estimate: ___________ -### PT report / peer writing review +### Peer writing review (use for PRs with PDF and/or Word drafts of PT reports) -See https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md +See also [writing review guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md) - [ ] All necessary source files are pushed to the repo and the report has been compiled without errors - [ ] Unrelated or unnescessary files aren't included (e.g. Latex .toc files) From db9eaab111a2b29d4938c4aa0ddf1580c5d071e9 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:48:40 -0400 Subject: [PATCH 11/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 8e66a166..619ead6d 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -6,7 +6,7 @@ Here, describe your changes in detail. Give a short background on the report, outline important questions or details for the reviewer, and add links to any supporting documents (e.g., protocol presentation). It's helpful to add links to the key files with the unique ID for the commit (a.k.a. the "SHA" or "hash"). -Make sure to include any known issues as well. +Make sure to include any known outstanding issues as well (and if they will be addressed in future PRs). ## Reflection From e28c0448ecb0e07ae9a6fa51d73611f1f65a24f6 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:50:13 -0400 Subject: [PATCH 12/35] add link to VISCtemplates and VISCfunctions repos --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 619ead6d..12adbe8d 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -10,7 +10,7 @@ Make sure to include any known outstanding issues as well (and if they will be a ## Reflection -Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any GitHub issues in the VISCtemplates or VISCfunctions repos been created that would help for future projects? +Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any relevant GitHub issues in the [VISCtemplates](https://github.com/FredHutch/VISCtemplates) or [VISCfunctions](https://github.com/FredHutch/VISCfunctions) repos been created that would help for future projects? ## Checklist(s) From 05a020ba5f363ba57f1269b1e26696b5161b81f5 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:51:30 -0400 Subject: [PATCH 13/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 12adbe8d..0c9aef8c 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -21,7 +21,7 @@ Checklists should be completed before a pull request is submitted for review. No ### Documentation (use for all PRs) - [ ] Appropriate README.md files have been updated -- [ ] Necessary context for the analysis is given +- [ ] Necessary context for the analysis is documented ### Code review (use for From d8918732bd3d3d54b6a8412f69524c6e1d4f3a3f Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:51:51 -0400 Subject: [PATCH 14/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 0c9aef8c..be280543 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -20,8 +20,8 @@ Checklists should be completed before a pull request is submitted for review. No ### Documentation (use for all PRs) -- [ ] Appropriate README.md files have been updated - [ ] Necessary context for the analysis is documented +- [ ] Appropriate project README.md files have been updated ### Code review (use for From b8360d4c058f4f9821480b8fe7b8725e2b576083 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 17:57:06 -0400 Subject: [PATCH 15/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index be280543..29b31144 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -23,11 +23,18 @@ Checklists should be completed before a pull request is submitted for review. No - [ ] Necessary context for the analysis is documented - [ ] Appropriate project README.md files have been updated -### Code review (use for +### Code review (use for PRs that include analysis code) See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) - [ ] I have compiled the R Markdown file(s) (or run the full R code) with no errors + - [ ] Running time has been recorded or estimated: ___________ +- [ ] Code is logically correct + - [ ] Joins are correct + - [ ] Any filtering is correct and in a logical order + - [ ] VISCtemplates and VISCfunctions are used whenever possible + - [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) + - [ ] For PT reports: the analysis code follows the statistical methods section - [ ] Code is readable and easy to understand, and follows the [VISC Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - [ ] Lines are at most 100 characters long - [ ] Consistent use of `<-` not `=` for assignment @@ -37,15 +44,7 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - [ ] Hard coding and magic numbers are avoided - - [ ] Supporting commentary is helpful and does not include debt or backup comments -- [ ] Code is logically correct - - [ ] Joins are correct - - [ ] Any filtering is correct and in a logical order -- [ ] Functions are properly documented -- [ ] The analysis code follows the statistical methods section -- [ ] VISCtemplates and VISCfunctions are used whenever possible -- [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) -- Time estimate: ___________ + - [ ] Comments are helpful and do not include debt (e.g. `# TODO:`) or commented-out backup code ### Peer writing review (use for PRs with PDF and/or Word drafts of PT reports) From d21065b1d9bd77350f697f61554c5cbade98e06f Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:02:47 -0400 Subject: [PATCH 16/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 29b31144..eb0435ee 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -53,18 +53,15 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] All necessary source files are pushed to the repo and the report has been compiled without errors - [ ] Unrelated or unnescessary files aren't included (e.g. Latex .toc files) - [ ] I've opened and checked compiled documents (.pdf, .docx) - - [ ] There are no Markdown/pandoc/Latex errors - [ ] No broken references (?? or ???) in the text (Use find: “??”) - [ ] There are no blank pages - - [ ] Page x out of y is correct (sometimes y is wrong) - -- [ ] Appropriate versions of R packages are used + - [ ] Page x out of y is correct (sometimes y is wrong) +- Appropriate versions of R packages are used - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used - [ ] If renv is used, I have run `renv::status()` and resolved any issues - -- [ ] The report text, including figure and table captions, follows the VISC writing guidelines (see https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) +- The report text, including figure and table captions, follows VISC convenctions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Objectives follow the SAP and study protocol - [ ] Results and summary sections map to the objectives @@ -72,23 +69,22 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] The correct tense is used throughout the report - [ ] Capitalization is correct and consistent - [ ] Acronyms are introduced the first time they're used within a major section - - [ ] I have reviewed the Results section - [ ] Figures and tables are sorted in parallel with results, and figure and table references are correct - [ ] Results listed in the text are correct and support my statements - [ ] Variables are used in referring to numeric values in the results section (to minimize human error) - -- [ ] Figures look right and follow the figure guidelines (see https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) +- [ ] Figures look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure - [ ] Text is not cut off (facet labels, legends, titles) - - [ ] Tables look right - [ ] Text is not running off the page - [ ] Significance highlighting is as expected -### Explanation for why any boxes above are NOT checked +## Notes + +Add any additional notes here. -If necessary, provide explanations here for why any boxes above are not checked. +If necessary, provide explanations here for why any boxes from the checklist(s) above are not checked. - Reason 1 - Reason 2 From 644e43eb8b0d614ea968a0323ab731e87813c218 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:05:39 -0400 Subject: [PATCH 17/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index eb0435ee..f18a7d6a 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -50,7 +50,7 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio See also [writing review guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md) -- [ ] All necessary source files are pushed to the repo and the report has been compiled without errors +- [ ] All necessary source files are pushed to the repo and the latest version of the report has been compiled without errors - [ ] Unrelated or unnescessary files aren't included (e.g. Latex .toc files) - [ ] I've opened and checked compiled documents (.pdf, .docx) - [ ] There are no Markdown/pandoc/Latex errors @@ -61,7 +61,7 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used - [ ] If renv is used, I have run `renv::status()` and resolved any issues -- The report text, including figure and table captions, follows VISC convenctions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) +- [ ] The report text, including figure and table captions, follows VISC conventions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Objectives follow the SAP and study protocol - [ ] Results and summary sections map to the objectives From b352b5e98284d7302b79a2f0594aa362d17c819c Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:18:26 -0400 Subject: [PATCH 18/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 33 ++++++++++++++----------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index f18a7d6a..b12d0f3f 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -18,23 +18,27 @@ Use one (or multiple) of the following checklists, depending on which type of PR Checklists should be completed before a pull request is submitted for review. Note: you can create a draft pull request before completing the checklist, then complete the checklist, and then mark the PR as ready for review. -### Documentation (use for all PRs) +### Documentation and completeness (use for all PRs) -- [ ] Necessary context for the analysis is documented -- [ ] Appropriate project README.md files have been updated +- [ ] Necessary context for the project/analysis has been documented +- [ ] Appropriate README.md files have been updated to reflect the latest changes +- [ ] The latest versions of all necessary source files have been pushed to the repo +- [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) -### Code review (use for PRs that include analysis code) +### Code review (use for PRs that include analysis or other source code) See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) -- [ ] I have compiled the R Markdown file(s) (or run the full R code) with no errors +- [ ] I have compiled the R Markdown file(s) (or run the relevant R code) with no errors - [ ] Running time has been recorded or estimated: ___________ - [ ] Code is logically correct - [ ] Joins are correct - [ ] Any filtering is correct and in a logical order - - [ ] VISCtemplates and VISCfunctions are used whenever possible - - [ ] VISCtemplates and VISCfunctions are installed from GitHub (not local) - [ ] For PT reports: the analysis code follows the statistical methods section +- [ ] Appropriate R packages are used + - [ ] VISCtemplates and VISCfunctions are used whenever possible + - [ ] No local package installations or unnescessary packages + - [ ] If renv is used, I have run `renv::status()` and resolved any issues - [ ] Code is readable and easy to understand, and follows the [VISC Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - [ ] Lines are at most 100 characters long - [ ] Consistent use of `<-` not `=` for assignment @@ -50,17 +54,16 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio See also [writing review guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md) -- [ ] All necessary source files are pushed to the repo and the latest version of the report has been compiled without errors - - [ ] Unrelated or unnescessary files aren't included (e.g. Latex .toc files) - - [ ] I've opened and checked compiled documents (.pdf, .docx) -- [ ] There are no Markdown/pandoc/Latex errors +- [ ] The latest version of the report has been compiled to both PDF and Word without errors + - [ ] I've opened and reviewed the compiled PDF document + - [ ] I've opened and reviewed the compiled Word document +- [ ] There are no obvious Markdown/pandoc/Latex errors - [ ] No broken references (?? or ???) in the text (Use find: “??”) - - [ ] There are no blank pages - - [ ] Page x out of y is correct (sometimes y is wrong) -- Appropriate versions of R packages are used + - [ ] No blank pages + - [ ] Page x out of y is correct (sometimes y is wrong) +- [ ] The reproducibility tables look correct - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used - - [ ] If renv is used, I have run `renv::status()` and resolved any issues - [ ] The report text, including figure and table captions, follows VISC conventions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Objectives follow the SAP and study protocol From 5d6365951292f6c8b70fe9c97e96aaa44f1d9af4 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:19:16 -0400 Subject: [PATCH 19/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index b12d0f3f..28950ab8 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -16,7 +16,7 @@ Describe any key challenges you faced in working on these changes. Were these ch Use one (or multiple) of the following checklists, depending on which type of PR you are doing. -Checklists should be completed before a pull request is submitted for review. Note: you can create a draft pull request before completing the checklist, then complete the checklist, and then mark the PR as ready for review. +Note: checklists should be completed before a pull request is submitted for review. You can create a draft pull request before completing the checklist, then complete the checklist, and then mark the PR as ready for review. ### Documentation and completeness (use for all PRs) From 6907c26f3a64431bb91ea1a48c506d1a947f888e Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:20:10 -0400 Subject: [PATCH 20/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 28950ab8..5be4e7c2 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -23,7 +23,7 @@ Note: checklists should be completed before a pull request is submitted for revi - [ ] Necessary context for the project/analysis has been documented - [ ] Appropriate README.md files have been updated to reflect the latest changes - [ ] The latest versions of all necessary source files have been pushed to the repo -- [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) + - [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) ### Code review (use for PRs that include analysis or other source code) From 0c213580f26a0f6568c4a1dc2fdefba05f9c05fa Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:21:14 -0400 Subject: [PATCH 21/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 5be4e7c2..a894dd8c 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -25,7 +25,7 @@ Note: checklists should be completed before a pull request is submitted for revi - [ ] The latest versions of all necessary source files have been pushed to the repo - [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) -### Code review (use for PRs that include analysis or other source code) +### Code review (use for PRs that include analysis or source code, including any R code) See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) From 56ad167a03156369fdb3547bfd9544ff3b9551e3 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:22:57 -0400 Subject: [PATCH 22/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index a894dd8c..4c4e11f5 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -25,7 +25,7 @@ Note: checklists should be completed before a pull request is submitted for revi - [ ] The latest versions of all necessary source files have been pushed to the repo - [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) -### Code review (use for PRs that include analysis or source code, including any R code) +### Code review (use for PRs that include any code, such as in .R or .Rmd files) See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) From 32e75281f4da586872d2d182b51b5f64d203533f Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:34:01 -0400 Subject: [PATCH 23/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 31 +++++++++++++------------ 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 4c4e11f5..401b6b0f 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -22,14 +22,14 @@ Note: checklists should be completed before a pull request is submitted for revi - [ ] Necessary context for the project/analysis has been documented - [ ] Appropriate README.md files have been updated to reflect the latest changes -- [ ] The latest versions of all necessary source files have been pushed to the repo +- [ ] The latest versions of all relevant files have been pushed to the repo - [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) ### Code review (use for PRs that include any code, such as in .R or .Rmd files) See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) -- [ ] I have compiled the R Markdown file(s) (or run the relevant R code) with no errors +- [ ] I have compiled the R Markdown file(s) (or run the relevant code) with no errors - [ ] Running time has been recorded or estimated: ___________ - [ ] Code is logically correct - [ ] Joins are correct @@ -67,21 +67,22 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] The report text, including figure and table captions, follows VISC conventions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Objectives follow the SAP and study protocol - - [ ] Results and summary sections map to the objectives + - [ ] Results and summary of main results sections map to the objectives - [ ] Text is spell-checked (including captions and footnotes) - - [ ] The correct tense is used throughout the report + - [ ] The correct tense (generally past tense) is used throughout the report - [ ] Capitalization is correct and consistent - - [ ] Acronyms are introduced the first time they're used within a major section -- [ ] I have reviewed the Results section - - [ ] Figures and tables are sorted in parallel with results, and figure and table references are correct - - [ ] Results listed in the text are correct and support my statements - - [ ] Variables are used in referring to numeric values in the results section (to minimize human error) -- [ ] Figures look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) - - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure - - [ ] Text is not cut off (facet labels, legends, titles) -- [ ] Tables look right - - [ ] Text is not running off the page - - [ ] Significance highlighting is as expected + - [ ] Acronyms and abbreviations are introduced the first time they are used +- [ ] I have reviewed the results carefully + - [ ] Everything mentioned in the Summary of Main Results is also in the Results section + - [ ] Statements in Results section are correct (including p-values) and supported by the correct figure and table references + - [ ] Variables are used in referring to numeric values in the Results section (to minimize human error) + - [ ] Figures and tables are sorted in parallel with mentions in Results section + - [ ] Figures look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) + - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure + - [ ] Text is not cut off (facet labels, legends, titles) + - [ ] Tables look right + - [ ] Text is not running off the page + - [ ] Significance highlighting is as expected ## Notes From 340483a0566f1eedc734d6878ee718d46a815f41 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Fri, 23 Aug 2024 18:42:26 -0400 Subject: [PATCH 24/35] Update NEWS.md --- NEWS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/NEWS.md b/NEWS.md index beb97ecc..d810a870 100644 --- a/NEWS.md +++ b/NEWS.md @@ -7,6 +7,7 @@ Bug fixes Other improvements * create_visc_project() now discards README.Rmd after knitting template to README.md (#223) * Update PT report naming practices to the format VDCnnn_assay_PTreport_interim/final_(un)blinded.Rmd +* Update analysis repo PR template to be more comprehensive and useful (#231) # VISCtemplates 1.3.2 From 4f3407f78680d0e2c64752a852add63b4a481efc Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Mon, 26 Aug 2024 10:38:50 -0700 Subject: [PATCH 25/35] fix type Co-authored-by: Bryan Mayer <39173901+mayerbry@users.noreply.github.com> --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 401b6b0f..fe2a5d4e 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -23,7 +23,7 @@ Note: checklists should be completed before a pull request is submitted for revi - [ ] Necessary context for the project/analysis has been documented - [ ] Appropriate README.md files have been updated to reflect the latest changes - [ ] The latest versions of all relevant files have been pushed to the repo - - [ ] Unrelated or unnescessary files aren't included (e.g., LaTeX .toc files) + - [ ] Unrelated or unnecessary files aren't included (e.g., LaTeX .toc files) ### Code review (use for PRs that include any code, such as in .R or .Rmd files) From b938473a87d6121340d5ba0f3f8692c85b0c2e2a Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Mon, 26 Aug 2024 10:39:24 -0700 Subject: [PATCH 26/35] split two checklist items apart Co-authored-by: Bryan Mayer <39173901+mayerbry@users.noreply.github.com> --- inst/templates/pull_request_template.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index fe2a5d4e..5608554b 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -48,7 +48,8 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - [ ] Hard coding and magic numbers are avoided - - [ ] Comments are helpful and do not include debt (e.g. `# TODO:`) or commented-out backup code + - [ ] Comments are helpful and do not include unaddressed debt (e.g. `# TODO:`) + - [ ] Commented-out backup code and unused chunks have been removed ### Peer writing review (use for PRs with PDF and/or Word drafts of PT reports) From 8173961237e8afe65252f8a1ed451fe04edbabef Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Mon, 26 Aug 2024 10:39:57 -0700 Subject: [PATCH 27/35] add to checklist searching for stray warnings and R output Co-authored-by: Bryan Mayer <39173901+mayerbry@users.noreply.github.com> --- inst/templates/pull_request_template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 5608554b..41e9e77b 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -60,6 +60,7 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] I've opened and reviewed the compiled Word document - [ ] There are no obvious Markdown/pandoc/Latex errors - [ ] No broken references (?? or ???) in the text (Use find: “??”) + - [ ] No stray warnings or R output in the text (Use find: “#”) - [ ] No blank pages - [ ] Page x out of y is correct (sometimes y is wrong) - [ ] The reproducibility tables look correct From ab444685f1f4428b578e731989488ea2555caf34 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Mon, 26 Aug 2024 10:41:09 -0700 Subject: [PATCH 28/35] add suppressed warnings to checklist Co-authored-by: Bryan Mayer <39173901+mayerbry@users.noreply.github.com> --- inst/templates/pull_request_template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 41e9e77b..cdd722f1 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -30,6 +30,7 @@ Note: checklists should be completed before a pull request is submitted for revi See also [code review guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/code-review-guideline.md) - [ ] I have compiled the R Markdown file(s) (or run the relevant code) with no errors + - [ ] Warnings are not suppressed. If a warning must be suppressed there is a clear explanation (i.e., comment). - [ ] Running time has been recorded or estimated: ___________ - [ ] Code is logically correct - [ ] Joins are correct From 2b03b998b9ba86ac815a05b6f85f96716d46a80d Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Mon, 26 Aug 2024 10:44:58 -0700 Subject: [PATCH 29/35] change wording about inserting numeric values in results section --- inst/templates/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index cdd722f1..a0dd7add 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -78,7 +78,7 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] I have reviewed the results carefully - [ ] Everything mentioned in the Summary of Main Results is also in the Results section - [ ] Statements in Results section are correct (including p-values) and supported by the correct figure and table references - - [ ] Variables are used in referring to numeric values in the Results section (to minimize human error) + - [ ] Code-based methods (i.e., in-line referencing) are used in inserting numeric values in the Results section (to minimize human error) - [ ] Figures and tables are sorted in parallel with mentions in Results section - [ ] Figures look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure From 6f34984fc755d6fe1c8466d6ec115cf2bab4e5cc Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Wed, 4 Sep 2024 11:07:20 -0700 Subject: [PATCH 30/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 68 +++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index a0dd7add..5f8b4e53 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -12,7 +12,7 @@ Make sure to include any known outstanding issues as well (and if they will be a Describe any key challenges you faced in working on these changes. Were these challenges unique to this project, or do you think they apply to other VISC projects as well? If not unique, have any relevant GitHub issues in the [VISCtemplates](https://github.com/FredHutch/VISCtemplates) or [VISCfunctions](https://github.com/FredHutch/VISCfunctions) repos been created that would help for future projects? -## Checklist(s) +## Checklist(s) for PR Creator Use one (or multiple) of the following checklists, depending on which type of PR you are doing. @@ -49,10 +49,10 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - [ ] Hard coding and magic numbers are avoided - - [ ] Comments are helpful and do not include unaddressed debt (e.g. `# TODO:`) + - [ ] Comments are helpful and do not include unaddressed debt (e.g. `# TODO:` or `# FIXME`) - [ ] Commented-out backup code and unused chunks have been removed -### Peer writing review (use for PRs with PDF and/or Word drafts of PT reports) +### Writing/report review (use for PRs with PDF and/or Word drafts of PT reports) See also [writing review guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing/writing_reviewing_guidelines.md) @@ -95,3 +95,65 @@ If necessary, provide explanations here for why any boxes from the checklist(s) - Reason 1 - Reason 2 + +## Checklist(s) for PR reviewer(s) + +Use one (or multiple) of the following checklists, depending on which type of PR this is. + +### Documentation and completeness + +- [ ] Necessary context for the project/analysis has been documented, and appropriate README.md files appear to be updated +- [ ] The latest versions of all relevant files appear to be pushed to the repo, and no unrelated or unnecessary files are included + +### Code review + +- [ ] If requested, I have compiled the R Markdown file(s) (or run the relevant code) on my end with no errors + - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems +- [ ] Warnings are not suppressed. If a warning must be suppressed there is a clear explanation (i.e., comment). +- [ ] There are no unused Rmd chunks or commented-out backup code +- [ ] Appropriate R packages are used + - [ ] VISCtemplates and VISCfunctions are used where possible + - [ ] No local package installations or apparently unused packages are included +- [ ] Code appears logically correct + - [ ] I have reviewed any joins and they appear correct + - [ ] I have reviewed any filtering and it appears correct and in a logical order +- [ ] Code is readable and easy to understand, and generally follows the [VISC Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) + - [ ] Lines are not excessively long + - [ ] Assignment operator `<-` is used consistently (rather than `=`) + - [ ] Object names are meaningful, descriptive, and use only alphanumeric characters and underscores (no dots) + - [ ] Object names are unique (no overwriting of previous variables) + - [ ] Hard coding and magic numbers are avoided + - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) + - [ ] Functions are organized and well-documented (with explanations of purpose, inputs, and ouput) + - [ ] Comments are helpful and do not include unaddressed debt (e.g. `# TODO:` or `# FIXME`) +- [ ] For PT reports: the analysis code follows the statistical methods section + +### Writing/report review + +- [ ] Both PDF and Word versions of the report are included and generally look acceptable +- [ ] There are no obvious Markdown/pandoc/Latex errors + - [ ] No broken references (?? or ???) in the text (Use find: “??”) + - [ ] No stray warnings or R output in the text (Use find: “#”) + - [ ] No blank pages + - [ ] Page x out of y is correct (sometimes y is wrong) +- [ ] The reproducibility tables look correct + - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages + - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used +- [ ] The sample type is accurate (e.g., serum, plasma, PBMC) +- [ ] Objectives follow the SAP and study protocol +- [ ] Results and summary of main results sections map to the objectives +- [ ] No obvious spelling errors (including captions and footnotes) +- [ ] The correct tense (generally past tense) is used throughout the report +- [ ] Capitalization is correct and consistent +- [ ] Acronyms and abbreviations are introduced the first time they are used +- [ ] I have reviewed the results sections + - [ ] Everything mentioned in the Summary of Main Results is also in the Results section + - [ ] Statements in Results section are correct (including p-values) and supported by the correct figure and table references +- [ ] I have reviewed the figures and tables + - [ ] Figures and tables are sorted in parallel with mentions in Results section + - [ ] Figures generally look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) + - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure + - [ ] Text is not cut off (facet labels, legends, titles) + - [ ] Tables generally look right + - [ ] Text is not running off the page + - [ ] Significance highlighting is as expected From dedebef15d58718ac9ab726f3e419289e5fff16c Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Wed, 4 Sep 2024 11:09:20 -0700 Subject: [PATCH 31/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 5f8b4e53..2a0e8590 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -32,9 +32,9 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] I have compiled the R Markdown file(s) (or run the relevant code) with no errors - [ ] Warnings are not suppressed. If a warning must be suppressed there is a clear explanation (i.e., comment). - [ ] Running time has been recorded or estimated: ___________ -- [ ] Code is logically correct - - [ ] Joins are correct - - [ ] Any filtering is correct and in a logical order +- [ ] I have reviewed the code for logical correctness + - [ ] I have double-checked any joins + - [ ] I have double-checked any filtering and it is in a logical order - [ ] For PT reports: the analysis code follows the statistical methods section - [ ] Appropriate R packages are used - [ ] VISCtemplates and VISCfunctions are used whenever possible From ef9aef94684f608b1fc059d54628d07eeeb9f3d7 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Wed, 4 Sep 2024 11:10:23 -0700 Subject: [PATCH 32/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 2a0e8590..79d3feb1 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -32,10 +32,10 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] I have compiled the R Markdown file(s) (or run the relevant code) with no errors - [ ] Warnings are not suppressed. If a warning must be suppressed there is a clear explanation (i.e., comment). - [ ] Running time has been recorded or estimated: ___________ -- [ ] I have reviewed the code for logical correctness +- [ ] I have reviewed the data processing and statistical analysis code for logical correctness - [ ] I have double-checked any joins - [ ] I have double-checked any filtering and it is in a logical order - - [ ] For PT reports: the analysis code follows the statistical methods section + - [ ] For PT reports: the analysis code follows and agrees with the statistical methods section - [ ] Appropriate R packages are used - [ ] VISCtemplates and VISCfunctions are used whenever possible - [ ] No local package installations or unnescessary packages From 291219cdcf3b13de8b00c6e5647a68ef075127b5 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Wed, 4 Sep 2024 11:18:15 -0700 Subject: [PATCH 33/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 79d3feb1..50f8619a 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -43,14 +43,14 @@ See also [code review guidelines](https://github.com/FredHutch/VISC-Documentatio - [ ] Code is readable and easy to understand, and follows the [VISC Coding Principles](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/Coding-Principles.md) document - [ ] Lines are at most 100 characters long - [ ] Consistent use of `<-` not `=` for assignment - - [ ] Object names include only alphanumeric characters and underscores (no dots) - - [ ] Object names are meaningful, descriptive, and unique (avoid overwriting previous variable) + - [ ] Object names are meaningful, descriptive, and use only alphanumeric characters and underscores (no dots) + - [ ] Object names are unique (no overwriting of previous variables) - [ ] Rmd code chunk names are descriptive and use dashes (not underscores or spaces) - - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) - [ ] Functions are organized and well-documented, with explanations of purpose, inputs, and ouput - - [ ] Hard coding and magic numbers are avoided - - [ ] Comments are helpful and do not include unaddressed debt (e.g. `# TODO:` or `# FIXME`) + - [ ] Comments do not include unaddressed debt (e.g. `# TODO:` or `# FIXME`) - [ ] Commented-out backup code and unused chunks have been removed + - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems (use `file.path()`) + - [ ] Hard coding and magic numbers are avoided ### Writing/report review (use for PRs with PDF and/or Word drafts of PT reports) @@ -67,18 +67,18 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] The reproducibility tables look correct - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used +- [ ] The sample type is accurate (e.g., serum, plasma, PBMC) +- [ ] Text has been spell-checked (including captions and footnotes) - [ ] The report text, including figure and table captions, follows VISC conventions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed) - - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Objectives follow the SAP and study protocol - [ ] Results and summary of main results sections map to the objectives - - [ ] Text is spell-checked (including captions and footnotes) + - [ ] Everything mentioned in the Summary of Main Results is also in the Results section - [ ] The correct tense (generally past tense) is used throughout the report - [ ] Capitalization is correct and consistent - [ ] Acronyms and abbreviations are introduced the first time they are used -- [ ] I have reviewed the results carefully - - [ ] Everything mentioned in the Summary of Main Results is also in the Results section - - [ ] Statements in Results section are correct (including p-values) and supported by the correct figure and table references - - [ ] Code-based methods (i.e., in-line referencing) are used in inserting numeric values in the Results section (to minimize human error) +- [ ] I have reviewed the results sections carefully and confirmed that the statements in Results section are correct (including p-values) and supported by the correct figure and table references + - [ ] Code-based methods (i.e., in-line referencing) are used in inserting numeric values in the Results section (to minimize human error) +- [ ] I have reviewed the figures and tables carefully - [ ] Figures and tables are sorted in parallel with mentions in Results section - [ ] Figures look right (refer to the [figure guidelines](https://github.com/FredHutch/VISC-Documentation/blob/main/Programming/figure-guidelines.md) as needed) - [ ] The appropriate number of axis tick marks is present (at least 3) for each figure From 5020c482f4c587fa12649e6d543f5330c8aea8cc Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Wed, 4 Sep 2024 11:19:40 -0700 Subject: [PATCH 34/35] Update pull_request_template.md --- inst/templates/pull_request_template.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index 50f8619a..eb3fec3b 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -111,9 +111,7 @@ Use one (or multiple) of the following checklists, depending on which type of PR - [ ] File paths are relative (except for trials and network drive paths) and portable across operating systems - [ ] Warnings are not suppressed. If a warning must be suppressed there is a clear explanation (i.e., comment). - [ ] There are no unused Rmd chunks or commented-out backup code -- [ ] Appropriate R packages are used - - [ ] VISCtemplates and VISCfunctions are used where possible - - [ ] No local package installations or apparently unused packages are included +- [ ] Appropriate R packages are used (VISCtemplates and VISCfunctions are used where possible, no local package installations or apparently unused packages) - [ ] Code appears logically correct - [ ] I have reviewed any joins and they appear correct - [ ] I have reviewed any filtering and it appears correct and in a logical order From ad35218f3140ff8cb23985af5c0361610d06e652 Mon Sep 17 00:00:00 2001 From: Kellie MacPhee Date: Thu, 5 Sep 2024 11:27:53 -0700 Subject: [PATCH 35/35] add note about data package version --- inst/templates/pull_request_template.md | 1 + 1 file changed, 1 insertion(+) diff --git a/inst/templates/pull_request_template.md b/inst/templates/pull_request_template.md index eb3fec3b..823955ae 100644 --- a/inst/templates/pull_request_template.md +++ b/inst/templates/pull_request_template.md @@ -67,6 +67,7 @@ See also [writing review guidelines](https://github.com/FredHutch/VISC-Documenta - [ ] The reproducibility tables look correct - [ ] The reproducibility tables do not include `NA`, local installations, or unnescessary packages - [ ] The most recent versions (note: not the development versions) of VISCtemplates and VISCfunctions are used + - [ ] The data package git hash refers to the correct branch/version (i.e., is up-to-date) - [ ] The sample type is accurate (e.g., serum, plasma, PBMC) - [ ] Text has been spell-checked (including captions and footnotes) - [ ] The report text, including figure and table captions, follows VISC conventions (refer to the [writing guidelines](https://github.com/FredHutch/VISC-Documentation/tree/main/Writing_Reviewing) as needed)