From 13684a876d3cd73480f309cac02f7b9097938b94 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Wed, 13 Mar 2024 16:27:06 -0400 Subject: [PATCH 1/7] add contributing md --- .github/workflows/starting-course.yml | 1 + CONTRIBUTING.md | 118 ++++++++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/.github/workflows/starting-course.yml b/.github/workflows/starting-course.yml index b85001af..b03d962c 100644 --- a/.github/workflows/starting-course.yml +++ b/.github/workflows/starting-course.yml @@ -50,6 +50,7 @@ jobs: resources/images/04-figures_files \ resources/chapt_screen_images \ Course_Name.rds \ + CONTRIBUTING.md \ docs/*.html \ docs/*.md \ manuscript/* diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..284227e0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,118 @@ +# Want to contribute to OTTR? + +## What are the different OTTR repositories/resources? + +Open-source Tools for Training Resources (OTTR) are a set of GitHub repositories designed to offer efficiency and flexibility in creating and maintaining training resources for courses and informatics tools. Below different repositories and resources that part of the OTTR universe are listed with brief explanations of what they do. The repositories and resources are split between "Functionality" and "Documentation" where the "Functionality" section focuses on the repositories or code that make OTTR functional; and the "Documentation" section focuses on the resources that explain how to use and maintain OTTR. + +### Functionality +#### OTTR_Template + +The [OTTR_Template repository](https://github.com/jhudsl/OTTR_Template) is a template used to create OTTR courses, specifically when you're writing one course, but publishing it in three places: (bookdown/website), Leanpub, and Coursera. If used with [a pull request model](https://www.ottrproject.org/writing_content_courses.html#about-ottr-and-pull-requests), courses built with the template will be checked for spelling errors and periodically for broken URLs, and can be previewed and automatically rendered after updates. + +#### OTTR_Quizzes + +The [OTTR_Quizzes repository](https://github.com/jhudsl/OTTR_Quizzes) can be used when you want your course quizzes to remain private rather being housed in a public, open source repository. Use of this repository is in conjunction with the main OTTR_Template. All edits and additions to non-quiz content should take place + +#### OTTR_Template_Website + +The [OTTR_Template_Website repository](https://github.com/jhudsl/OTTR_Template_Website) is a template used to create OTTR websites. Like the main OTTR_Template, if used with [a pull request model](https://www.ottrproject.org/writing_content_courses.html#about-ottr-and-pull-requests), websites built with the template will be checked for spelling errors and periodically for broken URLs, and can be previewed and automatically rendered after updates. Unlike the main OTTR_Template, it only produces a website as output. + +#### ottr-reports + +The [ottr-reports repository](https://github.com/jhudsl/ottr-reports) houses the functionality for reporting the results of the GitHub Action checks on spelling, URLs, and quiz formatting. + +#### ottrpal + +The [ottrpal repository](https://github.com/jhudsl/ottrpal) provides the functionality to convert an OTTR course to files ready for use in Leanpub and Coursera + +#### cow + +The [cow repository](https://github.com/jhudsl/cow) isn't officially an OTTR repository, but is a GitHub API wrapper in R which has additional functions to help wrangle GitHub published courses like OTTR courses. + +### Documentation + +#### ottrproject.org + +The [ottrproject.org repository](https://github.com/jhudsl/ottrproject.org) renders the [OTTR documentation website](https://www.ottrproject.org/). The repository is generated from the [OTTR_Template_Website template](https://github.com/jhudsl/OTTR_Template_Website). + +#### Wiki + +Listed as the "main OTTR guide" on some READMEs, there's an [OTTR wiki](https://github.com/jhudsl/OTTR_Template/wiki). + +#### OTTR paper + +There's an [OTTR paper](https://pubmed.ncbi.nlm.nih.gov/37207236/) published in the Journal of Statistics and Data Science Education by C. Savonen, C. Wright, A. Hoffman, et al. in 2023. [For information on citing the manuscript, see here](https://www.ottrproject.org/index.html#how-to-cite-ottr) + +#### Cheatsheets + +TBA + +#### Videos + +TBA + +## How should you suggest changes or alert us about problems? + +There are various ways in which you can request or suggest changes to OTTR. Below we discuss ways in which you can make suggestions or requests, but leave the implementation to others or implement the suggestions yourselves. + +### You want to make suggestions, but leave the implementation to someone else + +If you want to alert us about an issue or make suggestions, you can open a GitHub Issue or submit a response in our OTTR Feedback Google Form. + +#### GitHub Issues + +Open an issue describing the bug or feature request for the relevant repository using the following links. + +| Repository | Issues Link | +|:---------------------:|:---------------------------------------------------------------------------:| +| OTTR_Template | [Open an issue here](https://github.com/jhudsl/OTTR_Template/issues/new/choose) | +| OTTR_Quizzes | [Open an issue here](https://github.com/jhudsl/OTTR_Quizzes/issues/new/choose) | +| OTTR_Template_Website | [Open an issue here](https://github.com/jhudsl/OTTR_Template_Website/issues/new/choose)| +| ottr-reports | [Open an issue here](https://github.com/jhudsl/ottr-reports/issues/new/choose) | +| ottrpal | [Open an issue here](https://github.com/jhudsl/ottrpal/issues/new/choose) | +| cow | [Open an issue here](https://github.com/jhudsl/cow/issues/new/choose) | +| ottrproject.org | [Open an issue here](https://github.com/jhudsl/ottrpal/issues/new/choose) | + +##### Description of choices for issue type (if given) + +Most of the links above will directly open an issue for you to fill out a description of the problem or request, but several of the repositories provide choices (and related description templates) for the type of issue you want to open. Those choices could include the following: + +* **Feature Request** or **Course Template Feature Request**: Use this issue if you want to make a suggestion for an addition. +* **Problem Report** or **Course Template Problem Report**: Use this issue if you want to report a problem or possible improvement. +* **New Content Idea**: This is a template meant for opening an issue in an OTTR course, so that someone can suggest an additional topic or idea for that specific course. It shouldn't be used for opening an issue in one of these repos. +* **Course Problem Report**: This is a template meant for opening an issue in an OTTR course, so that someone can point out a problem or suggest an improvement for that specific course. It shouldn't be used for opening an issue in one of these repos. + +##### Assign an OTTR maintainer + +Assign an OTTR maintainer (`@cansavvy` or `@carriewright11`) to the issue. + +#### Google Form + +This [OTTR Feedback Google Form](https://docs.google.com/forms/d/e/1FAIpQLSfcc_h1MPfCOWyQup4Z76lzlBGz8cAkDQmBiqfxqOZ4_4lCkQ/viewform) can be used to ask questions about any problems you encounter or submit feedback such as ideas or requests for improvements. + +### You want to make suggestions, and implement them yourself! + +If you want to implement an improvement or fix a problem, open a branch, make the changes to the code there, and then open a pull request. [See this chapter "Using Version Control with GitHub"](https://jhudatascience.org/Adv_Reproducibility_in_Cancer_Informatics/using-version-control-with-github.html) from our Advanced Reproducibility course for more information on this pull request model if needed. + +#### Request Review + +Make sure to request review of your pull request from an OTTR maintainer (`@cansavvy` or `@carriewright11`). + +## What if you want to make several courses with similar branding using OTTR? + +If you plan to use the OTTR template several times for related courses within an organization and want each to have a shared branding or functionality variation, you may want to make your own template from the OTTR_Template, incorporating the stylistic changes in your spinoff template before making specific courses from the spinoff template. + +OTTR_Template --> Spinoff_Template (Make stylistic changes, mark as a template repository) --> Course Repository + +Examples that have done this include: + +| Spinoff template | Link | +|:------------------:|:-------------------------------------------------------------------------:| +| AnVIL Template | [GitHub Source Code](https://github.com/jhudsl/AnVIL_Template) | +| DataTrail Template | [GitHub Source Code](https://github.com/datatrail-jhu/DataTrail_Template) | + +If you are interested in this and have questions, reach out to the OTTR maintainers by filing a GitHub issue and assigning `@cansavvy` and `@carriewright11`. + +## Code of Conduct + +The [Contributor Covenant Code of Conduct can be found here](https://github.com/jhudsl/OTTR_Template/blob/main/code_of_conduct.md) From a9a0ca52db0cc0e1010a5859fbd1ae90db40e6e2 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Wed, 13 Mar 2024 16:49:39 -0400 Subject: [PATCH 2/7] add file to exclude for spell check --- resources/exclude_files.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/resources/exclude_files.txt b/resources/exclude_files.txt index cc77feed..4a7a93ea 100644 --- a/resources/exclude_files.txt +++ b/resources/exclude_files.txt @@ -2,3 +2,4 @@ About.Rmd docs/* style-sets/* manuscript/* +CONTRIBUTING.md From 50e5b8a111dfb314c3ea47930bba40e27f8926b5 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 14 Mar 2024 10:53:44 -0400 Subject: [PATCH 3/7] Update CONTRIBUTING.md Co-authored-by: Candace Savonen --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 284227e0..872b00e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,7 +57,9 @@ There are various ways in which you can request or suggest changes to OTTR. Belo ### You want to make suggestions, but leave the implementation to someone else -If you want to alert us about an issue or make suggestions, you can open a GitHub Issue or submit a response in our OTTR Feedback Google Form. +If you want to alert us about an issue or make suggestions, you can open a GitHub Issue or submit a response in our [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28). + +If you aren't sure what repository the suggestion pertains to -- or if the suggestion pertains to multiple repositories file it to the [`OTTR_Template` repo](https://github.com/jhudsl/OTTR_Template/issues/new/choose). #### GitHub Issues From 01de2fafa70a99784e8a60c0c50b75397959c165 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 14 Mar 2024 10:54:25 -0400 Subject: [PATCH 4/7] Update CONTRIBUTING.md Co-authored-by: Candace Savonen --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 872b00e5..745eaa03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,7 +81,7 @@ Most of the links above will directly open an issue for you to fill out a descri * **Feature Request** or **Course Template Feature Request**: Use this issue if you want to make a suggestion for an addition. * **Problem Report** or **Course Template Problem Report**: Use this issue if you want to report a problem or possible improvement. -* **New Content Idea**: This is a template meant for opening an issue in an OTTR course, so that someone can suggest an additional topic or idea for that specific course. It shouldn't be used for opening an issue in one of these repos. +* **New Content Idea**: This is a template meant for opening an issue in an OTTR course, so that someone can suggest an additional topic or idea for that specific course. It can be used for general suggestions for content. * **Course Problem Report**: This is a template meant for opening an issue in an OTTR course, so that someone can point out a problem or suggest an improvement for that specific course. It shouldn't be used for opening an issue in one of these repos. ##### Assign an OTTR maintainer From 03bbd318429103925c3a6c28a2b0f42b02cc93d3 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 14 Mar 2024 10:54:47 -0400 Subject: [PATCH 5/7] Update CONTRIBUTING.md Co-authored-by: Candace Savonen --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 745eaa03..c0957d32 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,7 +86,7 @@ Most of the links above will directly open an issue for you to fill out a descri ##### Assign an OTTR maintainer -Assign an OTTR maintainer (`@cansavvy` or `@carriewright11`) to the issue. +Assign an OTTR maintainer (`@cansavvy` or `@carriewright11` or `@avahoffman`) to the issue. If you aren't sure who the issue pertains to, assign `@cansavvy` and she'll make sure it gets to the right person. #### Google Form From e32c659aa84bd37b0fdc4268a6b67f20beed7287 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 14 Mar 2024 10:55:19 -0400 Subject: [PATCH 6/7] Update CONTRIBUTING.md Co-authored-by: Candace Savonen --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0957d32..ba0911d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -112,6 +112,8 @@ Examples that have done this include: |:------------------:|:-------------------------------------------------------------------------:| | AnVIL Template | [GitHub Source Code](https://github.com/jhudsl/AnVIL_Template) | | DataTrail Template | [GitHub Source Code](https://github.com/datatrail-jhu/DataTrail_Template) | +|Quarto website| [GitHub Source Code](https://github.com/fhdsl/OTTR_Quarto)| +|Metric collection dashboard template| [GitHub Source Code](https://github.com/fhdsl/metricminer-dashboard)| If you are interested in this and have questions, reach out to the OTTR maintainers by filing a GitHub issue and assigning `@cansavvy` and `@carriewright11`. From 520834517635eb81cb6af79c926d946f84355712 Mon Sep 17 00:00:00 2001 From: Kate Isaac <41767733+kweav@users.noreply.github.com> Date: Thu, 14 Mar 2024 11:37:07 -0400 Subject: [PATCH 7/7] move code of conduct, add ava maintainer, remove wiki --- CONTRIBUTING.md | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ba0911d2..c011e0bb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,9 @@ # Want to contribute to OTTR? +## Code of Conduct + +The [Contributor Covenant Code of Conduct can be found here](https://github.com/jhudsl/OTTR_Template/blob/main/code_of_conduct.md) + ## What are the different OTTR repositories/resources? Open-source Tools for Training Resources (OTTR) are a set of GitHub repositories designed to offer efficiency and flexibility in creating and maintaining training resources for courses and informatics tools. Below different repositories and resources that part of the OTTR universe are listed with brief explanations of what they do. The repositories and resources are split between "Functionality" and "Documentation" where the "Functionality" section focuses on the repositories or code that make OTTR functional; and the "Documentation" section focuses on the resources that explain how to use and maintain OTTR. @@ -35,10 +39,6 @@ The [cow repository](https://github.com/jhudsl/cow) isn't officially an OTTR rep The [ottrproject.org repository](https://github.com/jhudsl/ottrproject.org) renders the [OTTR documentation website](https://www.ottrproject.org/). The repository is generated from the [OTTR_Template_Website template](https://github.com/jhudsl/OTTR_Template_Website). -#### Wiki - -Listed as the "main OTTR guide" on some READMEs, there's an [OTTR wiki](https://github.com/jhudsl/OTTR_Template/wiki). - #### OTTR paper There's an [OTTR paper](https://pubmed.ncbi.nlm.nih.gov/37207236/) published in the Journal of Statistics and Data Science Education by C. Savonen, C. Wright, A. Hoffman, et al. in 2023. [For information on citing the manuscript, see here](https://www.ottrproject.org/index.html#how-to-cite-ottr) @@ -59,7 +59,7 @@ There are various ways in which you can request or suggest changes to OTTR. Belo If you want to alert us about an issue or make suggestions, you can open a GitHub Issue or submit a response in our [OTTR Feedback Google Form](https://forms.gle/jGQnd5oemHWyuUq28). -If you aren't sure what repository the suggestion pertains to -- or if the suggestion pertains to multiple repositories file it to the [`OTTR_Template` repo](https://github.com/jhudsl/OTTR_Template/issues/new/choose). +If you aren't sure what repository the suggestion pertains to -- or if the suggestion pertains to multiple repositories file it to the [`OTTR_Template` repo](https://github.com/jhudsl/OTTR_Template/issues/new/choose). #### GitHub Issues @@ -81,12 +81,12 @@ Most of the links above will directly open an issue for you to fill out a descri * **Feature Request** or **Course Template Feature Request**: Use this issue if you want to make a suggestion for an addition. * **Problem Report** or **Course Template Problem Report**: Use this issue if you want to report a problem or possible improvement. -* **New Content Idea**: This is a template meant for opening an issue in an OTTR course, so that someone can suggest an additional topic or idea for that specific course. It can be used for general suggestions for content. +* **New Content Idea**: This is a template meant for opening an issue in an OTTR course, so that someone can suggest an additional topic or idea for that specific course. It can be used for general suggestions for content. * **Course Problem Report**: This is a template meant for opening an issue in an OTTR course, so that someone can point out a problem or suggest an improvement for that specific course. It shouldn't be used for opening an issue in one of these repos. ##### Assign an OTTR maintainer -Assign an OTTR maintainer (`@cansavvy` or `@carriewright11` or `@avahoffman`) to the issue. If you aren't sure who the issue pertains to, assign `@cansavvy` and she'll make sure it gets to the right person. +Assign an OTTR maintainer (`@cansavvy` or `@carriewright11` or `@avahoffman`) to the issue. If you aren't sure who the issue pertains to, assign `@cansavvy` and she'll make sure it gets to the right person. #### Google Form @@ -98,7 +98,7 @@ If you want to implement an improvement or fix a problem, open a branch, make th #### Request Review -Make sure to request review of your pull request from an OTTR maintainer (`@cansavvy` or `@carriewright11`). +Make sure to request review of your pull request from an OTTR maintainer (`@cansavvy` or `@carriewright11` or `@avahoffman`). ## What if you want to make several courses with similar branding using OTTR? @@ -112,11 +112,7 @@ Examples that have done this include: |:------------------:|:-------------------------------------------------------------------------:| | AnVIL Template | [GitHub Source Code](https://github.com/jhudsl/AnVIL_Template) | | DataTrail Template | [GitHub Source Code](https://github.com/datatrail-jhu/DataTrail_Template) | -|Quarto website| [GitHub Source Code](https://github.com/fhdsl/OTTR_Quarto)| +|Quarto website| [GitHub Source Code](https://github.com/fhdsl/OTTR_Quarto)| |Metric collection dashboard template| [GitHub Source Code](https://github.com/fhdsl/metricminer-dashboard)| -If you are interested in this and have questions, reach out to the OTTR maintainers by filing a GitHub issue and assigning `@cansavvy` and `@carriewright11`. - -## Code of Conduct - -The [Contributor Covenant Code of Conduct can be found here](https://github.com/jhudsl/OTTR_Template/blob/main/code_of_conduct.md) +If you are interested in this and have questions, reach out to the OTTR maintainers by filing a GitHub issue and assigning `@cansavvy`, `@carriewright11`, and `@avahoffman`.