From ddd53960df095f34ddaf5f7a4fca83e83648fda9 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Wed, 20 Mar 2024 11:34:27 -0700 Subject: [PATCH 1/7] Add skeleton GHA for starting website --- .github/workflows/starting-website.yml | 72 ++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 .github/workflows/starting-website.yml diff --git a/.github/workflows/starting-website.yml b/.github/workflows/starting-website.yml new file mode 100644 index 0000000..cf05275 --- /dev/null +++ b/.github/workflows/starting-website.yml @@ -0,0 +1,72 @@ +# Code adapted from https://github.com/JetBrains/intellij-platform-plugin-template/blob/deb171483598ee8a5d7621154db880e87b4db4ef/.github/workflows/template-cleanup.yml +# by Candace Savonen for this repository. + +name: Starting a website + +on: + push: + branches: [ main, staging ] + workflow_dispatch: + +jobs: + # Run cleaning process only if workflow is triggered by not being in the Bookdown template anymore + template-cleanup: + name: Template Cleanup + runs-on: ubuntu-latest + if: github.event.repository.name != 'OTTR_Template_Website' + steps: + - name: checkout repo + uses: actions/checkout@v4 + + - name: Login as jhudsl-robot + run: | + git config --global --add safe.directory $GITHUB_WORKSPACE + git config --global user.email "itcrtrainingnetwork@gmail.com" + git config --global user.name "jhudsl-robot" + + - name: New Course - Set Repository Settings + uses: peter-evans/create-issue-from-file@v4 + with: + title: New Course - Set Repository Settings + content-filepath: .github/automatic-issues/set-repo-settings.md + labels: automated training issue + + # Issue for what needs to be edited + - name: New Course - Templates to Edit + uses: peter-evans/create-issue-from-file@v4 + with: + title: New Course - Templates to Edit + content-filepath: .github/automatic-issues/templates-to-edit.md + labels: automated training issue + + # Issue for how to enroll repo for updates + - name: New Course - Template Update Enrollment + uses: peter-evans/create-issue-from-file@v4 + with: + title: New Course - Template Update Enrollment + content-filepath: .github/automatic-issues/update-enrollment.md + labels: automated training issue + + # Issue for adding a method of feedback + - name: Reminder - Add a method of user feedback + uses: peter-evans/create-issue-from-file@v4 + with: + title: Reminder - Add user feedback method + content-filepath: .github/automatic-issues/add-feedback-method.md + labels: automated training issue + + - name: Get organization name + id: get_org_name + run: | + org_name=$(dirname ${{github.repository}}) + echo "org_name=$org_name" >> $GITHUB_OUTPUT + echo $org_name + + # Issue for adding the course to the jhudsl library + - name: Reminder - Add to jhudsl library + if: ${{ steps.get_org_name.outputs.org_name == 'jhudsl' }} + uses: peter-evans/create-issue-from-file@v4 + with: + title: Reminder - Add to jhudsl library + content-filepath: .github/automatic-issues/add-to-library.md + labels: automated training issue From d61cb8e85ae3f77583bf18d0787420ee975d1365 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Wed, 20 Mar 2024 11:36:03 -0700 Subject: [PATCH 2/7] Rename GHA --- .../workflows/{starting-website.yml => file-automatic-issues.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{starting-website.yml => file-automatic-issues.yml} (100%) diff --git a/.github/workflows/starting-website.yml b/.github/workflows/file-automatic-issues.yml similarity index 100% rename from .github/workflows/starting-website.yml rename to .github/workflows/file-automatic-issues.yml From aa0201a321c902c041c405369bb8d1fdd6bedcb6 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Wed, 20 Mar 2024 11:46:58 -0700 Subject: [PATCH 3/7] Add more skeleton GHAs from OTTR_Template --- .../automatic-issues/add-feedback-method.md | 4 +++ .github/automatic-issues/git-secrets.md | 14 ++++++++ .github/automatic-issues/images-checklist.md | 25 ++++++++++++++ .github/automatic-issues/set-repo-settings.md | 24 +++++++++++++ .github/automatic-issues/templates-to-edit.md | 34 +++++++++++++++++++ .github/automatic-issues/update-enrollment.md | 9 +++++ 6 files changed, 110 insertions(+) create mode 100644 .github/automatic-issues/add-feedback-method.md create mode 100644 .github/automatic-issues/git-secrets.md create mode 100644 .github/automatic-issues/images-checklist.md create mode 100644 .github/automatic-issues/set-repo-settings.md create mode 100644 .github/automatic-issues/templates-to-edit.md create mode 100644 .github/automatic-issues/update-enrollment.md diff --git a/.github/automatic-issues/add-feedback-method.md b/.github/automatic-issues/add-feedback-method.md new file mode 100644 index 0000000..799ff4d --- /dev/null +++ b/.github/automatic-issues/add-feedback-method.md @@ -0,0 +1,4 @@ + +To help users report issues or areas of improvement for your website, you should provide a clear method of feedback for your users to route their concerns through. + +[Read this chapter from an OTTR-made website about how to obtain user feedback](https://jhudatascience.org/Documentation_and_Usability/obtaining-user-feedback.html). diff --git a/.github/automatic-issues/git-secrets.md b/.github/automatic-issues/git-secrets.md new file mode 100644 index 0000000..da8a7da --- /dev/null +++ b/.github/automatic-issues/git-secrets.md @@ -0,0 +1,14 @@ + +**Note these steps are only pertinent if you are setting up this website outside of the jhudsl organization** + +For more information on these settings see instructions in the [getting started on ottrproject.org](https://www.ottrproject.org/getting_started.html#6_Set_up_your_GitHub_personal_access_token). + +It's important that these are set up and named exactly what they are below in order for Github actions to work correctly. + +To set up these repository secrets, on your repository's main Github page, go to `Settings` and scroll down to see `Secrets` on the left side menu bar. + +- [ ] Set `GH_PAT` +`Name`: `GH_PAT` +`value`: A personal access token [following these instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-token). +Underneath `Select scopes`, check both `repo` and `workflow`. +Then copy the PAT and save as the value. diff --git a/.github/automatic-issues/images-checklist.md b/.github/automatic-issues/images-checklist.md new file mode 100644 index 0000000..4a54618 --- /dev/null +++ b/.github/automatic-issues/images-checklist.md @@ -0,0 +1,25 @@ + +Use this checklist to make sure your slides and images are set up correctly! + +See [Setting Up Images and Graphics](https://www.ottrproject.org/writing_content.html#set-up-images) for more info! + +- [ ] Create your website's main Google Slides. + +- [ ] The slides use the appropriate template. + +- [ ] Each slide is described in the notes of the slide so learners relying on a screen reader can access the content. See https://lastcallmedia.com/blog/accessible-comics for more guidance on this. + +- [ ] The color palette choices of the slide are contrasted in a way that is friendly to those with color vision deficiencies. +You can check this using [Color Oracle](https://colororacle.org/). + +- [ ] Every image is inserted into the text using one of these options: `ottrpal::include_slide()`, `knitr::include_image()`, or this format: `SOMETHING`. + +- [ ] Every image has alternative text added to it. + +- [ ] The beginning of each Rmd contains this chunk so the images are saved in the correct spot: + +````` +```{r, include = FALSE} +ottrpal::set_knitr_image_path() +``` +````` diff --git a/.github/automatic-issues/set-repo-settings.md b/.github/automatic-issues/set-repo-settings.md new file mode 100644 index 0000000..ea642e7 --- /dev/null +++ b/.github/automatic-issues/set-repo-settings.md @@ -0,0 +1,24 @@ + +For more information on these settings see instructions in [Starting a new OTTR website](https://www.ottrproject.org/getting_started.html#starting-a-new-ottr-course). + +- [ ] This website repository is set to `public`. +- [ ] [Add the `jhudsl-robot` as a collaborator to your repository.](https://www.ottrproject.org/getting_started.html#5_Add_jhudsl-robot_as_a_collaborator). + +- [ ] [Github secret `GH_PAT` has been set](https://www.ottrproject.org/getting_started.html#6_Set_up_your_GitHub_personal_access_token) + `Name`: `GH_PAT` + `value`: A personal access token [following these instructions](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-token). + Underneath `Select scopes`, check both `repo` and `workflow`. + Then copy the PAT and save as the value. + +- [ ] GitHub pages is turned on + - [ ] Go to `Settings` > `Pages`. Underneath `Source`, choose `main` for the branch and select the `docs` folder. Then click `Save`. + - [ ] Check `Enforce HTTPS`. + +- [ ] [Set branch protections settings](https://www.ottrproject.org/getting_started.html#8_Set_up_branch_rules) + - [ ] `main` branch has been set up: + - [ ] `Require pull request reviews before merging` box is checked. + - [ ] `Require status checks to pass before merging` box is checked. + - [ ] Underneath that `Require branches to be up to date before merging` box is checked. + - [ ] Click `Save` at the bottom of the page! + +- [ ] [Customize GitHub actions](https://www.ottrproject.org/customize-robots.html) for what you will need in this website. diff --git a/.github/automatic-issues/templates-to-edit.md b/.github/automatic-issues/templates-to-edit.md new file mode 100644 index 0000000..e32f7b4 --- /dev/null +++ b/.github/automatic-issues/templates-to-edit.md @@ -0,0 +1,34 @@ + +[Follow the instructions here in ottrproject.org](https://www.ottrproject.org/writing_content.html) for details on how to start editing your OTTR website + +The following files need to be edited to get this new website started! + +### Files that need edited upon creating a new website. + +- [ ] `README.md` - Fill in all the `{ }`. +- [ ] `index.Rmd` - `title:` should be updated. +- [ ] `01-intro.Rmd` - replace the information there with information pertinent to this new website. +- [ ] `02-chapter_of_website.Rmd` - This Rmd has examples of how to set things up, if you don't need it as a reference, it can be deleted. + +### Files that need to be edited upon adding each new chapter (including upon creating a new website): + +- [ ] `_bookdown.yml` - The list of Rmd files that need to be rendered needs to be updated. See [instructions](https://www.ottrproject.org/examples.html#publishing-with-bookdown). +- [ ] `book.bib` - any citations need to be added. See [instructions](https://www.ottrproject.org/more_features.html#citing-sources). + +### Picking a style + +See more [about customizing style on this page in the guide](https://www.ottrproject.org/customize-style.html). +By default this website template will use the jhudsl data science lab style. However, you can customize and switch this to another style set. + +#### Using a style set + +[Read more about the style sets here](https://www.ottrproject.org/customize-style.html#Using_a_style_set). + +- [ ] On a new branch, copy the `style-sets//index.Rmd` and `style-sets//_output.yml` to the top of the repository to overwrite the default `index.Rmd` and `_output.yml`. +- [ ] Copy over all the files in the `style-sets//copy-to-assets` to the `assets` folder in the top of the repository. +- [ ] [Create a pull request](https://www.ottrproject.org/writing_content.html#Open_a_pull_request) with these changes, and double check the rendered preview to make sure that the style is what you are looking for. + +### Files that need to be edited upon adding new packages that the book's code uses: + +- `docker/Dockerfile` needs to have the new package added so it will be installed. See [instructions](https://www.ottrproject.org/customize-docker.html). +- The code chunk in `index.Rmd` should be edited to add the new package. diff --git a/.github/automatic-issues/update-enrollment.md b/.github/automatic-issues/update-enrollment.md new file mode 100644 index 0000000..6cb6ba4 --- /dev/null +++ b/.github/automatic-issues/update-enrollment.md @@ -0,0 +1,9 @@ + +The original template: https://github.com/jhudsl/OTTR_Template is always a work in progress. +We are working on adding more features and smoothing out bugs as we go. + +If you want to receive updates from the original template to your website template, you will need to enroll this repository to the template updates by adding it to the `sync.yml` file. + +- [ ] [Follow these instructions](https://www.ottrproject.org/getting_started.html#9_Enroll_your_repository_for_OTTR_updates) to enroll your website repository to receive these updates. + +- [ ] [Ensure that you have followed these instructions](https://www.ottrproject.org/getting_started.html#5_Add_jhudsl-robot_as_a_collaborator) to add the `jhudsl-robot` as a collaborator to your repository. From 6f47d64359e14d0458bc37949d1947054bdf58a5 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Wed, 20 Mar 2024 11:47:05 -0700 Subject: [PATCH 4/7] Gitignore .DS_Store --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 5b6a065..7b732e7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ .Rhistory .RData .Ruserdata +.DS_Store From e11d09d03aa2488ce79017d256b67a28ffd5d0f7 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Fri, 22 Mar 2024 13:37:43 -0700 Subject: [PATCH 5/7] Add md files of automatic issues --- .../automatic-issues/add-feedback-method.md | 4 --- .github/automatic-issues/images-checklist.md | 25 ------------------- .github/automatic-issues/set-repo-settings.md | 1 - .github/automatic-issues/templates-to-edit.md | 14 +++++------ .github/automatic-issues/update-enrollment.md | 4 +-- 5 files changed, 7 insertions(+), 41 deletions(-) delete mode 100644 .github/automatic-issues/add-feedback-method.md delete mode 100644 .github/automatic-issues/images-checklist.md diff --git a/.github/automatic-issues/add-feedback-method.md b/.github/automatic-issues/add-feedback-method.md deleted file mode 100644 index 799ff4d..0000000 --- a/.github/automatic-issues/add-feedback-method.md +++ /dev/null @@ -1,4 +0,0 @@ - -To help users report issues or areas of improvement for your website, you should provide a clear method of feedback for your users to route their concerns through. - -[Read this chapter from an OTTR-made website about how to obtain user feedback](https://jhudatascience.org/Documentation_and_Usability/obtaining-user-feedback.html). diff --git a/.github/automatic-issues/images-checklist.md b/.github/automatic-issues/images-checklist.md deleted file mode 100644 index 4a54618..0000000 --- a/.github/automatic-issues/images-checklist.md +++ /dev/null @@ -1,25 +0,0 @@ - -Use this checklist to make sure your slides and images are set up correctly! - -See [Setting Up Images and Graphics](https://www.ottrproject.org/writing_content.html#set-up-images) for more info! - -- [ ] Create your website's main Google Slides. - -- [ ] The slides use the appropriate template. - -- [ ] Each slide is described in the notes of the slide so learners relying on a screen reader can access the content. See https://lastcallmedia.com/blog/accessible-comics for more guidance on this. - -- [ ] The color palette choices of the slide are contrasted in a way that is friendly to those with color vision deficiencies. -You can check this using [Color Oracle](https://colororacle.org/). - -- [ ] Every image is inserted into the text using one of these options: `ottrpal::include_slide()`, `knitr::include_image()`, or this format: `SOMETHING`. - -- [ ] Every image has alternative text added to it. - -- [ ] The beginning of each Rmd contains this chunk so the images are saved in the correct spot: - -````` -```{r, include = FALSE} -ottrpal::set_knitr_image_path() -``` -````` diff --git a/.github/automatic-issues/set-repo-settings.md b/.github/automatic-issues/set-repo-settings.md index ea642e7..c28cbcc 100644 --- a/.github/automatic-issues/set-repo-settings.md +++ b/.github/automatic-issues/set-repo-settings.md @@ -2,7 +2,6 @@ For more information on these settings see instructions in [Starting a new OTTR website](https://www.ottrproject.org/getting_started.html#starting-a-new-ottr-course). - [ ] This website repository is set to `public`. -- [ ] [Add the `jhudsl-robot` as a collaborator to your repository.](https://www.ottrproject.org/getting_started.html#5_Add_jhudsl-robot_as_a_collaborator). - [ ] [Github secret `GH_PAT` has been set](https://www.ottrproject.org/getting_started.html#6_Set_up_your_GitHub_personal_access_token) `Name`: `GH_PAT` diff --git a/.github/automatic-issues/templates-to-edit.md b/.github/automatic-issues/templates-to-edit.md index e32f7b4..eaae3d5 100644 --- a/.github/automatic-issues/templates-to-edit.md +++ b/.github/automatic-issues/templates-to-edit.md @@ -1,19 +1,17 @@ -[Follow the instructions here in ottrproject.org](https://www.ottrproject.org/writing_content.html) for details on how to start editing your OTTR website +[Follow the instructions here in ottrproject.org](https://www.ottrproject.org/editing_website.html) for details on how to start editing your OTTR website. The following files need to be edited to get this new website started! ### Files that need edited upon creating a new website. -- [ ] `README.md` - Fill in all the `{ }`. -- [ ] `index.Rmd` - `title:` should be updated. -- [ ] `01-intro.Rmd` - replace the information there with information pertinent to this new website. -- [ ] `02-chapter_of_website.Rmd` - This Rmd has examples of how to set things up, if you don't need it as a reference, it can be deleted. +- [ ] `README.md` - Fill in the README with the title of the website, a brief description of the website, and any other details that would be useful for anyone who encounters your website. +- [ ] `index.Rmd` - Update the `title` field. Since this Rmd file serves as the website's landing page, include any information you believe will be beneficial for visitors upon their arrival. -### Files that need to be edited upon adding each new chapter (including upon creating a new website): -- [ ] `_bookdown.yml` - The list of Rmd files that need to be rendered needs to be updated. See [instructions](https://www.ottrproject.org/examples.html#publishing-with-bookdown). -- [ ] `book.bib` - any citations need to be added. See [instructions](https://www.ottrproject.org/more_features.html#citing-sources). +### Files that need to be edited upon adding each new page. + +- [ ] `_site.yml` - Include the title of your newly created page in the `text` field, and insert the corresponding html file name into the `href` field. ### Picking a style diff --git a/.github/automatic-issues/update-enrollment.md b/.github/automatic-issues/update-enrollment.md index 6cb6ba4..5cc0a81 100644 --- a/.github/automatic-issues/update-enrollment.md +++ b/.github/automatic-issues/update-enrollment.md @@ -1,9 +1,7 @@ -The original template: https://github.com/jhudsl/OTTR_Template is always a work in progress. +The original template: https://github.com/jhudsl/OTTR_Template_Website is always a work in progress. We are working on adding more features and smoothing out bugs as we go. If you want to receive updates from the original template to your website template, you will need to enroll this repository to the template updates by adding it to the `sync.yml` file. - [ ] [Follow these instructions](https://www.ottrproject.org/getting_started.html#9_Enroll_your_repository_for_OTTR_updates) to enroll your website repository to receive these updates. - -- [ ] [Ensure that you have followed these instructions](https://www.ottrproject.org/getting_started.html#5_Add_jhudsl-robot_as_a_collaborator) to add the `jhudsl-robot` as a collaborator to your repository. From 921f73b6e0cbad448ac5004bb4d8c274e1905b23 Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Fri, 22 Mar 2024 13:37:55 -0700 Subject: [PATCH 6/7] Add GHA for filing automatic issues --- .github/workflows/file-automatic-issues.yml | 30 --------------------- 1 file changed, 30 deletions(-) diff --git a/.github/workflows/file-automatic-issues.yml b/.github/workflows/file-automatic-issues.yml index cf05275..389126b 100644 --- a/.github/workflows/file-automatic-issues.yml +++ b/.github/workflows/file-automatic-issues.yml @@ -18,12 +18,6 @@ jobs: - name: checkout repo uses: actions/checkout@v4 - - name: Login as jhudsl-robot - run: | - git config --global --add safe.directory $GITHUB_WORKSPACE - git config --global user.email "itcrtrainingnetwork@gmail.com" - git config --global user.name "jhudsl-robot" - - name: New Course - Set Repository Settings uses: peter-evans/create-issue-from-file@v4 with: @@ -46,27 +40,3 @@ jobs: title: New Course - Template Update Enrollment content-filepath: .github/automatic-issues/update-enrollment.md labels: automated training issue - - # Issue for adding a method of feedback - - name: Reminder - Add a method of user feedback - uses: peter-evans/create-issue-from-file@v4 - with: - title: Reminder - Add user feedback method - content-filepath: .github/automatic-issues/add-feedback-method.md - labels: automated training issue - - - name: Get organization name - id: get_org_name - run: | - org_name=$(dirname ${{github.repository}}) - echo "org_name=$org_name" >> $GITHUB_OUTPUT - echo $org_name - - # Issue for adding the course to the jhudsl library - - name: Reminder - Add to jhudsl library - if: ${{ steps.get_org_name.outputs.org_name == 'jhudsl' }} - uses: peter-evans/create-issue-from-file@v4 - with: - title: Reminder - Add to jhudsl library - content-filepath: .github/automatic-issues/add-to-library.md - labels: automated training issue From c225350f83052106540be17de45e231ab19a1e1d Mon Sep 17 00:00:00 2001 From: Howard Baek <50791792+howardbaek@users.noreply.github.com> Date: Fri, 22 Mar 2024 13:41:41 -0700 Subject: [PATCH 7/7] One final commit before PR --- .github/workflows/file-automatic-issues.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/file-automatic-issues.yml b/.github/workflows/file-automatic-issues.yml index 389126b..e24658d 100644 --- a/.github/workflows/file-automatic-issues.yml +++ b/.github/workflows/file-automatic-issues.yml @@ -17,7 +17,8 @@ jobs: steps: - name: checkout repo uses: actions/checkout@v4 - + + # Issue for what repository settings need to be set - name: New Course - Set Repository Settings uses: peter-evans/create-issue-from-file@v4 with: