From b1e44d4dfd458a3d793d90a86a5b4de3647ef657 Mon Sep 17 00:00:00 2001 From: Daniel Mazhari-Jensen Date: Mon, 10 Aug 2026 10:35:49 +0200 Subject: [PATCH 1/3] =?UTF-8?q?ci:=20=F0=9F=91=B7=20update-checks-n-typos?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pre-commit-config, typos.toml, and check-gh-workflow. --- .config/typos.toml | 8 +++ .github/workflows/checks.yml | 97 ++++++++++++++++++++++++++++++++++++ .pre-commit-config.yaml | 34 ++++++------- .vscode/settings.json | 1 + 4 files changed, 121 insertions(+), 19 deletions(-) create mode 100644 .config/typos.toml create mode 100644 .github/workflows/checks.yml diff --git a/.config/typos.toml b/.config/typos.toml new file mode 100644 index 0000000..8dd4e99 --- /dev/null +++ b/.config/typos.toml @@ -0,0 +1,8 @@ +[files] +extend-exclude = [ + "*.html", + "*.css", + ".quarto/*", + "_site/*", + "*.svg" +] diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml new file mode 100644 index 0000000..20be897 --- /dev/null +++ b/.github/workflows/checks.yml @@ -0,0 +1,97 @@ +name: Checks + +on: pull_request + +permissions: read-all + +jobs: + check-template: + runs-on: ubuntu-latest + steps: + # This is a useful security step to check for unexpected outbound calls from the runner, + # which could indicate a compromised token or runner. + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 + with: + egress-policy: audit + + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Set up uv + uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + with: + enable-cache: true + + - name: Install justfile + run: uv tool install rust-just + + # Set this user so that the checks create Git commits. + - name: Set bot user + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + + # TODO: Confirm name of recipe to check template creation. + - name: Check template creation + run: just test-all + + check-typos: + runs-on: ubuntu-latest + steps: + # This is a useful security step to check for unexpected outbound calls from the runner, + # which could indicate a compromised token or runner. + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 + with: + egress-policy: audit + + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Spell check repo + uses: crate-ci/typos@cf5f1c29a8ac336af8568821ec41919923b05a83 # v1.45.1 + with: + config: .config/typos.toml + + check-website-build: + runs-on: ubuntu-latest + steps: + # This is a useful security step to check for unexpected outbound calls from the runner, + # which could indicate a compromised token or runner. + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 + with: + egress-policy: audit + + - name: Checkout repository + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Set up Quarto + uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0 + + # Check that the website builds, but don't publish it + - name: Render Quarto Project + uses: quarto-dev/quarto-actions/render@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0 + + # Dependency Review Action + # + # This Action will scan dependency manifest files that change as part of a Pull Request, + # surfacing known-vulnerable versions of the packages declared or updated in the PR. + # Once installed, if the workflow run is marked as required, + # PRs introducing known-vulnerable packages will be blocked from merging. + # + # Source repository: https://github.com/actions/dependency-review-action + check-dependencies: + runs-on: ubuntu-latest + steps: + - name: Harden the runner (Audit all outbound calls) + uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 + with: + egress-policy: audit + + - name: "Checkout Repository" + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: "Dependency Review" + uses: actions/dependency-review-action@3c4e3dcb1aa7874d2c16be7d79418e9b7efd6261 # v4.8.2 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 54e2b9f..97085b5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -10,30 +10,26 @@ repos: hooks: - id: gitleaks - - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v6.0.0 - hooks: - - id: trailing-whitespace - - id: end-of-file-fixer - - id: mixed-line-ending - args: [ --fix=lf ] - - id: check-merge-conflict - args: [ --assume-in-merge ] - - - repo: https://github.com/commitizen-tools/commitizen - rev: v4.17.0 - hooks: - - id: commitizen - # Use the mirror since the main `typos` repo has tags for different # sub-packages, which confuses pre-commit when it tries to find the latest # version - repo: https://github.com/adhtruong/mirrors-typos - rev: v1.48.0 + rev: v1.45.1 hooks: - id: typos + args: [--config, .config/typos.toml, --force-exclude] + + - repo: https://github.com/jolars/panache-pre-commit + rev: v2.51.0 + hooks: + - id: panache-format - - repo: https://github.com/rvben/rumdl-pre-commit - rev: v0.2.49 + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v6.0.0 hooks: - - id: rumdl-fmt # Auto-format + - id: trailing-whitespace + - id: end-of-file-fixer + - id: mixed-line-ending + args: [--fix=lf] + - id: check-merge-conflict + args: [--assume-in-merge] diff --git a/.vscode/settings.json b/.vscode/settings.json index 66cf316..5baecbc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -26,6 +26,7 @@ "*.qmd.jinja": "jinja-md" }, "files.insertFinalNewline": true, + "typos.config": ".config/typos.toml", "conventionalCommits.emojiFormat": "emoji", "conventionalCommits.promptScopes": false } From 00ae6ba60b903d9bff97a293789a75e9ebfca124 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 10 Aug 2026 08:37:59 +0000 Subject: [PATCH 2/3] =?UTF-8?q?chore:=20=E2=9C=8F=EF=B8=8F=20automatic=20p?= =?UTF-8?q?re-commit=20hook=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 404.qmd | 4 +- CHANGELOG.md | 60 +++--- CODE_OF_CONDUCT.md | 35 ++-- CONTRIBUTING.md | 137 +++++++------- README.md | 79 ++++---- README.qmd | 62 +++---- docs/guide/installing.qmd | 53 +++--- docs/guide/next-steps.qmd | 214 ++++++++++------------ docs/guide/updating.qmd | 51 +++--- docs/guide/using.qmd | 48 +++-- docs/includes/_badges.qmd | 16 +- index.qmd | 82 ++++----- template/404.qmd | 4 +- template/CODE_OF_CONDUCT.md | 35 ++-- template/README.qmd | 80 ++++---- template/appendix/for-teachers.qmd | 8 +- template/includes/_badges.qmd | 16 +- template/includes/_star-us.qmd | 9 +- template/includes/_survey.qmd | 3 +- template/overview/is-this-for-you.qmd | 18 +- template/overview/learning-design.qmd | 131 ++++++------- template/overview/schedule.qmd | 38 ++-- template/overview/syllabus.qmd | 9 +- template/pre-workshop/code-of-conduct.qmd | 109 ++++++----- template/pre-workshop/survey.qmd | 19 +- template/sessions/conclusion.qmd | 4 +- template/sessions/introduction.qmd | 4 +- template/sessions/session.qmd | 6 +- 28 files changed, 636 insertions(+), 698 deletions(-) diff --git a/404.qmd b/404.qmd index f28249f..767f5d4 100644 --- a/404.qmd +++ b/404.qmd @@ -2,5 +2,5 @@ title: "The page you are looking for does not exist" --- -This page does not exist, go back to the [homepage](/index.qmd) or check -the URL for typos. +This page does not exist, go back to the [homepage](/index.qmd) or check the URL +for typos. diff --git a/CHANGELOG.md b/CHANGELOG.md index d51dce6..e7e9084 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,25 +1,23 @@ # Changelog -Since we follow -[Conventional Commits](https://decisions.seedcase-project.org/why-conventional-commits/) -we're able to automatically create formal "releases" of the workshop -based on our commit messages. Releases in the context of workshops are -simply snapshots in time of the workshop content. The releases are -published to Zenodo for easier discovery, archival, and citation -purposes. We use +Since we follow [Conventional +Commits](https://decisions.seedcase-project.org/why-conventional-commits/) we're +able to automatically create formal "releases" of the workshop based on our +commit messages. Releases in the context of workshops are simply snapshots in +time of the workshop content. The releases are published to Zenodo for easier +discovery, archival, and citation purposes. We use [Commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen/) -to automatically create these releases using -[SemVer](https://semverdoc.org) as the version numbering scheme. +to automatically create these releases using [SemVer](https://semverdoc.org) as +the version numbering scheme. -Because releases are created based on commit messages, a new release can -be created quite often---sometimes several times in a day. This also -means that any individual release will not have many changes within it. -Below is a list of the releases we've made so far, along with what was -changed within each release. +Because releases are created based on commit messages, a new release can be +created quite often---sometimes several times in a day. This also means that any +individual release will not have many changes within it. Below is a list of the +releases we've made so far, along with what was changed within each release. -If you attended a workshop or used the workshop material as some point -in time, you can always refer to this changelog page to find out what -has been changed since you last used it. +If you attended a workshop or used the workshop material as some point in time, +you can always refer to this changelog page to find out what has been changed +since you last used it. ## 0.11.0 (2026-06-04) @@ -101,10 +99,8 @@ has been changed since you last used it. - :sparkles: add badges to landing page - :sparkles: standardize table widths of schedule -- :see_no_evil: some `.vdoc.*` type files are created by Quarto, ignore - them -- :sparkles: include hidden contributor list sections in README and - index +- :see_no_evil: some `.vdoc.*` type files are created by Quarto, ignore them +- :sparkles: include hidden contributor list sections in README and index ### Fix @@ -119,8 +115,7 @@ has been changed since you last used it. - :hammer: rename `style` to `format-r` in justfile - :pencil2: use quotes around values in `_quarto.yml` - :recycle: include `@sec-` links to chapters along with a link -- :technologist: simplify pull request template after Markdown formatter - added +- :technologist: simplify pull request template after Markdown formatter added - :wrench: indent by 2 in Markdown files in `.editorconfig` - :recycle: install uv directly, rather than first pipx - :arrow_up: update pre-commit hook versions @@ -182,8 +177,7 @@ has been changed since you last used it. ### Refactor -- :recycle: output `get-contributors.sh` as text, send to file in - justfile +- :recycle: output `get-contributors.sh` as text, send to file in justfile ## 0.4.12 (2025-09-03) @@ -260,8 +254,8 @@ has been changed since you last used it. ### Refactor - :memo: simplify some text of the README -- :recycle: replace ending of `_contributors.yml` with newline for - pre-commit styling +- :recycle: replace ending of `_contributors.yml` with newline for pre-commit + styling - :hammer: exclude justfile when listing TODOs - :hammer: use `quarto update` to match recipe name - :arrow_up: update pre-commit hook versions @@ -368,12 +362,10 @@ has been changed since you last used it. - :recycle: switch to using bash in `check-commits` justfile - :memo: fix link to instructor guide - :fire: don't need the update from template workflow -- :recycle: switch to using `github_user` and `github_repo` for project - naming +- :recycle: switch to using `github_user` and `github_repo` for project naming - :recycle: use lowercase for workshop type naming - :recycle: set Zenodo upload type to `lesson` -- :recycle: moved version information for installing into - `_metadata.yml` +- :recycle: moved version information for installing into `_metadata.yml` - :recycle: match syllabus structure to that done in GitHub Intro - :fire: session isn't always an R workshop, don't need code chunk @@ -405,9 +397,7 @@ has been changed since you last used it. - :truck: converted includes into own pages in template - :recycle: remove social time from schedule - :recycle: include a starting URL for Quarto website in Netlify -- :construction_worker: merge template website build workflow into one - file +- :construction_worker: merge template website build workflow into one file - :recycle: expand on template's CONTRIBUTING doc - :truck: move code of conduct out of includes as own page -- :recycle: use only one `.cz.toml`, but use internal 'if' statements - inside +- :recycle: use only one `.cz.toml`, but use internal 'if' statements inside diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 6f8f13c..22171e4 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,28 +1,25 @@ # Contributor Code of Conduct -As contributors and maintainers of this project, we pledge to respect -all people who contribute through reporting issues, posting suggestions, -updating any material, submitting pull requests, and other activities. +As contributors and maintainers of this project, we pledge to respect all people +who contribute through reporting issues, posting suggestions, updating any +material, submitting pull requests, and other activities. -We are committed to making participation in this project a -harassment-free experience for everyone, regardless of level of -experience, gender, gender identity and expression, sexual orientation, -disability, personal appearance, body size, race, ethnicity, age, or -religion. +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, or religion. -Examples of unacceptable behavior by participants include the use of -sexual language or imagery, derogatory comments or personal attacks, -trolling, public or private harassment, insults, or other unprofessional -conduct. +Examples of unacceptable behavior by participants include the use of sexual +language or imagery, derogatory comments or personal attacks, trolling, public +or private harassment, insults, or other unprofessional conduct. -Project maintainers have the right and responsibility to remove, edit, -or reject comments, commits, code, wiki edits, issues, and other -contributions that are not aligned to this Code of Conduct. Project -maintainers who do not follow the Code of Conduct may be removed from -the project team. +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct. Project maintainers who do not follow the +Code of Conduct may be removed from the project team. -Instances of abusive, harassing, or otherwise unacceptable behavior may -be reported by opening an issue or contacting one or more of the project +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by opening an issue or contacting one or more of the project maintainers. This Code of Conduct is adapted from the Contributor Covenant diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fba2d6..de37f83 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,109 +2,102 @@ ## :bug: Issues and bugs -The easiest way to contribute is to report issues or bugs that you might -find while using the Template Workshop. You can do this by creating a -[new](https://github.com/rostools/template-workshop/issues/new/) issue -on our GitHub repository. +The easiest way to contribute is to report issues or bugs that you might find +while using the Template Workshop. You can do this by creating a +[new](https://github.com/rostools/template-workshop/issues/new/) issue on our +GitHub repository. ## :pencil2: Adding or modifying content If you would like to contribute content, please check out our -[guide](https://guides.rostools.org/contributing) for more specific -details on how we work and develop. It is a regularly evolving document, -so is at various states of completion. +[guide](https://guides.rostools.org/contributing) for more specific details on +how we work and develop. It is a regularly evolving document, so is at various +states of completion. To contribute to the Template Workshop, you first need to install [uv](https://docs.astral.sh/uv/) and -[justfile](https://just.systems/man/en/packages.html). We use uv and -justfile to manage our project, such as to run checks and test the -template. Both the uv and justfile websites have a more detailed guide -on using uv, but below are some simple instructions to get you started. +[justfile](https://just.systems/man/en/packages.html). We use uv and justfile to +manage our project, such as to run checks and test the template. Both the uv and +justfile websites have a more detailed guide on using uv, but below are some +simple instructions to get you started. -It's easiest to first -[install uv](https://docs.astral.sh/uv/getting-started/installation/) -and then install justfile with uv. Once you've installed uv, install -justfile by running: +It's easiest to first [install +uv](https://docs.astral.sh/uv/getting-started/installation/) and then install +justfile with uv. Once you've installed uv, install justfile by running: -``` bash +```bash uv tool install rust-just ``` -We keep all our development workflows in the `justfile`, so you can -explore it to see what commands are available. To see a list of commands -available, run: +We keep all our development workflows in the `justfile`, so you can explore it +to see what commands are available. To see a list of commands available, run: -``` bash +```bash just ``` -As you contribute, make sure your changes will pass our tests by opening -a terminal so that the working directory is the root of this project +As you contribute, make sure your changes will pass our tests by opening a +terminal so that the working directory is the root of this project (`template-workshop/`) and running: -``` bash +```bash just run-all ``` -When testing the template, Copier can only use content kept in the Git -history. Meaning that if you make changes to the template and try to -test it, it won't be able to test those changes. You have to commit the -changes first in order for Copier to use them. +When testing the template, Copier can only use content kept in the Git history. +Meaning that if you make changes to the template and try to test it, it won't be +able to test those changes. You have to commit the changes first in order for +Copier to use them. -When committing changes, please try to follow -[Conventional Commits](https://decisions.seedcase-project.org/why-conventional-commits/) -as Git messages. Using this convention allows us to be able to -automatically create a release based on the commit message by using +When committing changes, please try to follow [Conventional +Commits](https://decisions.seedcase-project.org/why-conventional-commits/) as +Git messages. Using this convention allows us to be able to automatically create +a release based on the commit message by using [Commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen/). -If you don't use Conventional Commits when making a commit, we will -revise the pull request title to follow that format, as we use squash -merges when merging pull requests, so all other commits in the pull -request will be squashed into one commit. +If you don't use Conventional Commits when making a commit, we will revise the +pull request title to follow that format, as we use squash merges when merging +pull requests, so all other commits in the pull request will be squashed into +one commit. ## :file_folder: Explanation of files and folders -This list describes the default files that are included in the template -as well as explains a bit more about them and what they are used for. - -- `.copier-answers.yml`: Contains the answers you gave when copying the - project from the template. - **You should not modify this file directly.** -- `.github/`: Contains GitHub-specific files, such as the workflow to - build the website from the Markdown files. -- `_quarto.yml`: Quarto configuration file for the website, including - settings for the website, such as the theme, navigation, and other - options. -- `.gitignore`: This ignore file tells Git which files to not track. - Unless you know what you are doing, it's best to not touch this file. -- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/) - configuration file for managing and running checks before each commit. -- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell - checker configuration file. -- `CITATION.cff`: Structured citation metadata for your project when - archived on [Zenodo](https://zenodo.org/) and used by GitHub to - display the citation information on the repository page. This is used - to add the metadata to Zenodo when a GitHub release has been uploaded - to Zenodo. -- `justfile`: [`just`](https://just.systems/man/en/) configuration file - for scripting project tasks. +This list describes the default files that are included in the template as well +as explains a bit more about them and what they are used for. + +- `.copier-answers.yml`: Contains the answers you gave when copying the project + from the template. **You should not modify this file directly.** +- `.github/`: Contains GitHub-specific files, such as the workflow to build the + website from the Markdown files. +- `_quarto.yml`: Quarto configuration file for the website, including settings + for the website, such as the theme, navigation, and other options. +- `.gitignore`: This ignore file tells Git which files to not track. Unless you + know what you are doing, it's best to not touch this file. +- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/) configuration + file for managing and running checks before each commit. +- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell checker + configuration file. +- `CITATION.cff`: Structured citation metadata for your project when archived on + [Zenodo](https://zenodo.org/) and used by GitHub to display the citation + information on the repository page. This is used to add the metadata to Zenodo + when a GitHub release has been uploaded to Zenodo. +- `justfile`: [`just`](https://just.systems/man/en/) configuration file for + scripting project tasks. - `.editorconfig`: Editor configuration file for - [EditorConfig](https://editorconfig.org/) to maintain consistent - coding styles across different editors and IDEs. + [EditorConfig](https://editorconfig.org/) to maintain consistent coding styles + across different editors and IDEs. - `CHANGELOG.md`: Changelog file for tracking changes in the project. - `CONTRIBUTING.md`: Guidelines for contributing to the project. -- `.github/`: Contains GitHub-specific files, such as issue and pull - request templates, workflows, +- `.github/`: Contains GitHub-specific files, such as issue and pull request + templates, workflows, [dependabot](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/dependabot-quickstart-guide) configuration, pull request templates, and a [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file. -- `_metadata.yml`: Quarto metadata file for the website, including - information about the project, such as the titles and GitHub names. -- `_quarto.yml`: Quarto configuration file for the website, including - settings for the website, such as the theme, navigation, and other - options. -- `.rumdl.toml`: [rumdl](https://rumdl.dev) configuration file for - formatting Markdown files in the project. -- `.cz.toml`: - [Commitizen](https://commitizen-tools.github.io/commitizen/) +- `_metadata.yml`: Quarto metadata file for the website, including information + about the project, such as the titles and GitHub names. +- `_quarto.yml`: Quarto configuration file for the website, including settings + for the website, such as the theme, navigation, and other options. +- `.rumdl.toml`: [rumdl](https://rumdl.dev) configuration file for formatting + Markdown files in the project. +- `.cz.toml`: [Commitizen](https://commitizen-tools.github.io/commitizen/) configuration file for managing versions and changelogs. diff --git a/README.md b/README.md index 38bfc2b..1986fad 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ - - # Template Workshop: An opinionated setup for making workshops as open educational resources [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16979956.svg)](https://doi.org/10.5281/zenodo.16979956) @@ -15,25 +13,23 @@ website](https://github.com/rostools/template-workshop/actions/workflows/build-w [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/rostools/template-workshop/main.svg)](https://results.pre-commit.ci/latest/github/rostools/template-workshop/main) [![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![Project Status: Active – The project has reached a stable, usable -state and is being actively +[![Project Status: Active -- The project has reached a stable, usable state and +is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) -This repository contains a -[Copier](https://copier.readthedocs.io/en/stable/) template for setting -up a new repository for a workshop. We made template-workshop because we -manage and develop several workshops in rostools, and this template is -designed to make it easier to create, develop, and maintain those -workshops. - -The template helps set up and maintain workshop repositories, which -contain files to create a website for a workshop and that might also be -used as an open educational resource (OVER). Use this template to quickly -get started with a new workshop with all the necessary files and -configurations in place for a smoother “developer experience” and to -have [continuous -delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) -of the workshop website and archival to Zenodo. +This repository contains a [Copier](https://copier.readthedocs.io/en/stable/) +template for setting up a new repository for a workshop. We made +template-workshop because we manage and develop several workshops in rostools, +and this template is designed to make it easier to create, develop, and maintain +those workshops. + +The template helps set up and maintain workshop repositories, which contain +files to create a website for a workshop and that might also be used as an open +educational resource (OVER). Use this template to quickly get started with a new +workshop with all the necessary files and configurations in place for a smoother +"developer experience" and to have [continuous +delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) of the +workshop website and archival to Zenodo. Check out our [website](https://template-workshop.rostools.org) for more information, such as the features it provides and a @@ -43,18 +39,17 @@ template. For a list of changes, see our [changelog](CHANGELOG.md) page. > [!TIP] > > This template repository was generated from the -> [t-squared](https://github.com/seedcase-project/t-squared) Seedcase -> template :tada: +> [t-squared](https://github.com/seedcase-project/t-squared) Seedcase template +> :tada: ## Contributing -Check out our [contributing page](CONTRIBUTING.md) for information on -how to contribute to the project, including how to set up your -development environment. +Check out our [contributing page](CONTRIBUTING.md) for information on how to +contribute to the project, including how to set up your development environment. Please note that this project is released with a [Contributor Code of -Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree -to abide by its terms. +Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to +abide by its terms. ### Contributors @@ -70,22 +65,24 @@ This project is licensed under the [MIT License](LICENSE.md). ## Citing -This project is part of rostools, which is an organisation that hosts -and runs workshops (also as open educational resources) that are related -in some way to doing reproducible and open science. If you use this -template in your work, please cite it as follows: +This project is part of rostools, which is an organisation that hosts and runs +workshops (also as open educational resources) that are related in some way to +doing reproducible and open science. If you use this template in your work, +please cite it as follows: -Johnston L.W., Brødbæk S.K. (2025). Template Workshop: An opinionated -setup for making workshops as open educational resources DOI: -10.5281/zenodo.16979956 URL: https://template-workshop.rostools.org +Johnston L.W., Brødbæk S.K. (2025). Template Workshop: An opinionated setup for +making workshops as open educational resources DOI: 10.5281/zenodo.16979956 URL: +https://template-workshop.rostools.org Or as a BibTeX entry: - @misc{YourReferenceHere, - author = {Johnston, Luke William and Brødbæk, Signe Kirk}, - doi = {10.5281/zenodo.16979956}, - month = {8}, - title = {Template Workshop: An opinionated setup for making workshops as open educational resources}, - url = {https://template-workshop.rostools.org}, - year = {2025} - } +``` +@misc{YourReferenceHere, +author = {Johnston, Luke William and Brødbæk, Signe Kirk}, +doi = {10.5281/zenodo.16979956}, +month = {8}, +title = {Template Workshop: An opinionated setup for making workshops as open educational resources}, +url = {https://template-workshop.rostools.org}, +year = {2025} +} +``` diff --git a/README.qmd b/README.qmd index 8f4eefa..b3c0dd1 100644 --- a/README.qmd +++ b/README.qmd @@ -11,42 +11,39 @@ metadata-files: {{< include /docs/includes/_badges.qmd >}} -This repository contains a -[Copier](https://copier.readthedocs.io/en/stable/) template for setting -up a new repository for a workshop. We made {{< meta gh.repo >}} because -we manage and develop several workshops in rostools, and this template -is designed to make it easier to create, develop, and maintain those -workshops. - -The template helps set up and maintain workshop repositories, which -contain files to create a website for a workshop and that might also be -used as an open educational resource (OVER). Use this template to quickly -get started with a new workshop with all the necessary files and -configurations in place for a smoother "developer experience" and to -have -[continuous delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) -of the workshop website and archival to Zenodo. - -Check out our [website]({{< meta links.site >}}) for more information, -such as the features it provides and a -[guide]({{< meta links.site >}}/docs/guide) to using the template. For a -list of changes, see our [changelog](CHANGELOG.md) page. +This repository contains a [Copier](https://copier.readthedocs.io/en/stable/) +template for setting up a new repository for a workshop. We made +{{< meta gh.repo >}} because we manage and develop several workshops in +rostools, and this template is designed to make it easier to create, develop, +and maintain those workshops. + +The template helps set up and maintain workshop repositories, which contain +files to create a website for a workshop and that might also be used as an open +educational resource (OVER). Use this template to quickly get started with a new +workshop with all the necessary files and configurations in place for a smoother +"developer experience" and to have [continuous +delivery/deployment](https://en.wikipedia.org/wiki/Continuous_delivery) of the +workshop website and archival to Zenodo. + +Check out our [website]({{< meta links.site >}}) for more information, such as +the features it provides and a [guide]({{< meta links.site >}}/docs/guide) to +using the template. For a list of changes, see our [changelog](CHANGELOG.md) +page. ::: callout-tip This template repository was generated from the -[t-squared](https://github.com/seedcase-project/t-squared) Seedcase -template :tada: +[t-squared](https://github.com/seedcase-project/t-squared) Seedcase template +:tada: ::: ## Contributing -Check out our [contributing page](CONTRIBUTING.md) for information on -how to contribute to the project, including how to set up your -development environment. +Check out our [contributing page](CONTRIBUTING.md) for information on how to +contribute to the project, including how to set up your development environment. -Please note that this project is released with a -[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in -this project you agree to abide by its terms. +Please note that this project is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to +abide by its terms. ### Contributors @@ -58,13 +55,14 @@ This project is licensed under the [MIT License](LICENSE.md). ## Citing -This project is part of rostools, which is an organisation that hosts -and runs workshops (also as open educational resources) that are related -in some way to doing reproducible and open science. If you use this -template in your work, please cite it as follows: +This project is part of rostools, which is an organisation that hosts and runs +workshops (also as open educational resources) that are related in some way to +doing reproducible and open science. If you use this template in your work, +please cite it as follows: ```{python} #| output: asis + !uvx --quiet cffconvert --format apalike ``` diff --git a/docs/guide/installing.qmd b/docs/guide/installing.qmd index 700836c..b2dce21 100644 --- a/docs/guide/installing.qmd +++ b/docs/guide/installing.qmd @@ -6,41 +6,38 @@ description: | order: 1 --- -There are a few programs that are required to use this template to -create a workshop: +There are a few programs that are required to use this template to create a +workshop: -- [uv](https://docs.astral.sh/uv/): A tool for managing Python - environments and running commands. -- [Python](https://www.python.org/): Required by Copier, the template - tool. -- [Copier](https://copier.readthedocs.io/en/stable/): A template tool - for making new workshops in a standardised and structured way. -- [just](https://just.systems/man/en/): A build and development - management tool that helps with running common build and check tasks. +- [uv](https://docs.astral.sh/uv/): A tool for managing Python environments and + running commands. +- [Python](https://www.python.org/): Required by Copier, the template tool. +- [Copier](https://copier.readthedocs.io/en/stable/): A template tool for making + new workshops in a standardised and structured way. +- [just](https://just.systems/man/en/): A build and development management tool + that helps with running common build and check tasks. You can use uv to install these required programs, so -[install](https://docs.astral.sh/uv/getting-started/installation/) that -first. After you've installed uv, install the other programs using: +[install](https://docs.astral.sh/uv/getting-started/installation/) that first. +After you've installed uv, install the other programs using: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} uv tool install copier rust-just ``` uv will also install Python for you when you install these tools. -There are some optional, though **strongly recommended**, programs to -install and use in any workshop created with this template: +There are some optional, though **strongly recommended**, programs to install +and use in any workshop created with this template: -- [Git](https://git-scm.com/): For version control and setting up Git to - track the newly created workshop. -- [Lychee](https://lychee.cli.rs/guides/getting-started/): A link - checker that we include in the `justfile` for checking for broken - links in the files. -- [Quarto](https://quarto.org/): A scientific and technical publishing - system built on Pandoc. The website built with this template is - created with Quarto, and the workshop created from this template is - also set up to use Quarto too. -- [gh cli](https://cli.github.com/): For managing GitHub repositories - and settings from the command line. There are some post-creation steps - we've included that use gh to simplify setting up a GitHub repository - for the workshop. +- [Git](https://git-scm.com/): For version control and setting up Git to track + the newly created workshop. +- [Lychee](https://lychee.cli.rs/guides/getting-started/): A link checker that + we include in the `justfile` for checking for broken links in the files. +- [Quarto](https://quarto.org/): A scientific and technical publishing system + built on Pandoc. The website built with this template is created with Quarto, + and the workshop created from this template is also set up to use Quarto too. +- [gh cli](https://cli.github.com/): For managing GitHub repositories and + settings from the command line. There are some post-creation steps we've + included that use gh to simplify setting up a GitHub repository for the + workshop. diff --git a/docs/guide/next-steps.qmd b/docs/guide/next-steps.qmd index f0df3dc..12187c3 100644 --- a/docs/guide/next-steps.qmd +++ b/docs/guide/next-steps.qmd @@ -5,65 +5,62 @@ description: | order: 4 --- -While most of the post-applying steps are listed in the created -`TODO.md` file within the workshop, this documents some more details for -these steps. Use this guide alongside the `TODO.md` to complete those -tasks. For example, one of the first tasks is to start having Git track -the workshop with `git init`. +While most of the post-applying steps are listed in the created `TODO.md` file +within the workshop, this documents some more details for these steps. Use this +guide alongside the `TODO.md` to complete those tasks. For example, one of the +first tasks is to start having Git track the workshop with `git init`. ## Setting up pre-commit hooks -[Pre-commit hooks](https://pre-commit.com/) are scripts that run when -committing changes to a Git repository. They are incredibly useful for -enforcing coding standards and catching errors early. The `justfile` -contains a `install-precommit` recipe that sets up the pre-commit hooks -for your workshop. Run it by opening a terminal within the workshop -directory and running the following command: +[Pre-commit hooks](https://pre-commit.com/) are scripts that run when committing +changes to a Git repository. They are incredibly useful for enforcing coding +standards and catching errors early. The `justfile` contains a +`install-precommit` recipe that sets up the pre-commit hooks for your workshop. +Run it by opening a terminal within the workshop directory and running the +following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} just install-precommit ``` -This sets up the pre-commit hooks to run standard checks on your -repository whenever you commit files to the history. Using pre-commit -hooks as part of your workflow is even better if you connect the -continuous integration service to your repository. Go to the -[pre-commit.ci](https://pre-commit.ci/) website and follow the -instructions there to connect your repository to the service. This will -run the pre-commit hooks on every commit you push to the repository, -including pull requests, which will ensure that the code is checked for -basic issues. It will also keep the pre-commit hooks updated by creating -a pull request whenever newer versions of the hooks are available. +This sets up the pre-commit hooks to run standard checks on your repository +whenever you commit files to the history. Using pre-commit hooks as part of your +workflow is even better if you connect the continuous integration service to +your repository. Go to the [pre-commit.ci](https://pre-commit.ci/) website and +follow the instructions there to connect your repository to the service. This +will run the pre-commit hooks on every commit you push to the repository, +including pull requests, which will ensure that the code is checked for basic +issues. It will also keep the pre-commit hooks updated by creating a pull +request whenever newer versions of the hooks are available. ## Adding the Quarto theme ::: callout-warning -This step is only necessary if you are using this template for a -repository that is part of rostools. If you are using this template for -a different workshop, you can skip this step. If you have your own -Quarto theme that you want to use, you can use this step as a general -guide on how to add a Quarto theme to your workshop. +This step is only necessary if you are using this template for a repository that +is part of rostools. If you are using this template for a different workshop, +you can skip this step. If you have your own Quarto theme that you want to use, +you can use this step as a general guide on how to add a Quarto theme to your +workshop. ::: -For rostools repositories, we have a custom Quarto extension that has -our theme called `rostools-theme`. The `justfile` has a recipe called -`update-quarto-theme` that adds this theme to the workshop. Run it by -opening a terminal within the workshop directory and running the -following command: +For rostools repositories, we have a custom Quarto extension that has our theme +called `rostools-theme`. The `justfile` has a recipe called +`update-quarto-theme` that adds this theme to the workshop. Run it by opening a +terminal within the workshop directory and running the following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} just update-quarto-theme ``` -This adds the `rostools-theme` Quarto theme to the website, which -provides a consistent look and feel across all rostools websites. It's -called `update-quarto-theme` here since you can use this command to keep -the theme updated. +This adds the `rostools-theme` Quarto theme to the website, which provides a +consistent look and feel across all rostools websites. It's called +`update-quarto-theme` here since you can use this command to keep the theme +updated. -Then to use the theme, you need to update the `_quarto.yml` file by -adding the following lines to the `project` and `format` sections: +Then to use the theme, you need to update the `_quarto.yml` file by adding the +following lines to the `project` and `format` sections: -``` yaml +```yaml project: type: rostools-theme @@ -75,111 +72,102 @@ format: rostools-theme-html ## Setting up a GitHub repository ::: callout-warning -These series of steps are only necessary if you are using this template -for a repository that is part of rostools. If you want a quick way of -putting your workshop on GitHub, you can use the `gh` command line tool -to upload the workshop to GitHub: +These series of steps are only necessary if you are using this template for a +repository that is part of rostools. If you want a quick way of putting your +workshop on GitHub, you can use the `gh` command line tool to upload the +workshop to GitHub: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} gh repo create {{ github_repo_spec }} --source=. --public` ``` ::: -We have a custom command line tool that we developed to help manage -GitHub repositories for rostools repositories. While it's useful for us, -it isn't designed or build in a way that makes it easy for others to -use. +We have a custom command line tool that we developed to help manage GitHub +repositories for rostools repositories. While it's useful for us, it isn't +designed or build in a way that makes it easy for others to use. -For setting up a GitHub repository for the created workshop that will be -part of rostools, you'll need to install the Seedcase Project's (a -"sibling" organisation) internal tool -[`spaid`](https://github.com/seedcase-project/spaid) and use the -following commands to run the next setup steps: +For setting up a GitHub repository for the created workshop that will be part of +rostools, you'll need to install the Seedcase Project's (a "sibling" +organisation) internal tool [`spaid`](https://github.com/seedcase-project/spaid) +and use the following commands to run the next setup steps: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} spaid_gh_create_repo_from_local -h spaid_gh_set_repo_settings -h spaid_gh_ruleset_basic_protect_main -h spaid_gh_ruleset_require_pr -h ``` -Some configuration is needed after copying this template to a new -repository, including configuration external to the repository. Some -GitHub workflows require installing GitHub Apps, for greater security -purposes and easier administration when managing multiple repositories. -The -[security section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens) -in our [Guidebook](https://guidebook.seedcase-project.org/) provides -some instructions on how to set up GitHub Apps, secrets, and variables. -Ideally the secrets and variables should be set up in the organization -settings. The specific workflows in this template that require this -additional setup are: +Some configuration is needed after copying this template to a new repository, +including configuration external to the repository. Some GitHub workflows +require installing GitHub Apps, for greater security purposes and easier +administration when managing multiple repositories. The [security +section](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens) +in our [Guidebook](https://guidebook.seedcase-project.org/) provides some +instructions on how to set up GitHub Apps, secrets, and variables. Ideally the +secrets and variables should be set up in the organization settings. The +specific workflows in this template that require this additional setup are: - The workflow `.github/workflows/release.yml` requires the - [auto-release-token](https://github.com/apps/auto-release-token) - GitHub App, which is specific to the Seedcase Project but usable - within rostools, as well as a creating a GitHub secret called - `UPDATE_VERSION_TOKEN` and a variable called `UPDATE_VERSION_APP_ID` - that has the App ID. + [auto-release-token](https://github.com/apps/auto-release-token) GitHub App, + which is specific to the Seedcase Project but usable within rostools, as well + as a creating a GitHub secret called `UPDATE_VERSION_TOKEN` and a variable + called `UPDATE_VERSION_APP_ID` that has the App ID. - The workflow `.github/workflows/add-to-project.yml` requires the - [add-to-board-token](https://github.com/apps/add-to-board-token) - GitHub App (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` - secret and the `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. + [add-to-board-token](https://github.com/apps/add-to-board-token) GitHub App + (another Seedcase app), along with the `ADD_TO_BOARD_TOKEN` secret and the + `ADD_TO_BOARD_APP_ID` variable of the GitHub App's ID. ## Connecting to hosting services If you use this template to make a website hosted on -[Netlify](https://www.netlify.com/), you need to connect the GitHub -repository to Netlify. The Quarto documentation has an -[excellent guide](https://quarto.org/docs/publishing/netlify.html) on -how to do this. It includes configuring Netlify to host the website and -adding the +[Netlify](https://www.netlify.com/), you need to connect the GitHub repository +to Netlify. The Quarto documentation has an [excellent +guide](https://quarto.org/docs/publishing/netlify.html) on how to do this. It +includes configuring Netlify to host the website and adding the [`NETLIFY_AUTH_TOKEN`](https://quarto.org/docs/publishing/netlify.html#netlify-credentials) secret to the GitHub repository (or ideally at the organization level). -For hosting on [GitHub Pages](https://pages.github.com/), it's a bit -easier to set up than Netlify. The Quarto documentation again has a -[guide](https://quarto.org/docs/publishing/github-pages.html) on how to -do this. Before you can host on GitHub Pages, you need to use Quarto to -set things up for you, by running the following command: +For hosting on [GitHub Pages](https://pages.github.com/), it's a bit easier to +set up than Netlify. The Quarto documentation again has a +[guide](https://quarto.org/docs/publishing/github-pages.html) on how to do this. +Before you can host on GitHub Pages, you need to use Quarto to set things up for +you, by running the following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} quarto publish github-pages ``` ## Auto-releasing to Zenodo ::: callout-warning -This step is only necessary if you are using this template for a -repository that is part of rostools. If you are using this template for -a different workshop, you can skip this step. If you want to set up -auto-releasing to Zenodo for a different workshop, you can use this -section to guide you to setting it up for your workshop. +This step is only necessary if you are using this template for a repository that +is part of rostools. If you are using this template for a different workshop, +you can skip this step. If you want to set up auto-releasing to Zenodo for a +different workshop, you can use this section to guide you to setting it up for +your workshop. ::: -If you create a release on GitHub, either manually or through a GitHub -workflow, you can have that release automatically create a record on -Zenodo, which is a service that allows you to archive workshops and -create a DOI for it. - -GitHub and Zenodo have an integration that, when set up, will -automatically create a -[Zenodo record](https://help.zenodo.org/docs/deposit/about-records/) -from a -[GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases). -This is useful if you want to create a DOI for your workshop, which will -allow you or others to cite it in their work as well as provide more -exposure for your workshop. Connecting GitHub to Zenodo is very easy, -check out Zenodo's -[guide](https://help.zenodo.org/docs/github/archive-software/github-upload/) -on it. +If you create a release on GitHub, either manually or through a GitHub workflow, +you can have that release automatically create a record on Zenodo, which is a +service that allows you to archive workshops and create a DOI for it. + +GitHub and Zenodo have an integration that, when set up, will automatically +create a [Zenodo record](https://help.zenodo.org/docs/deposit/about-records/) +from a [GitHub +release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases). +This is useful if you want to create a DOI for your workshop, which will allow +you or others to cite it in their work as well as provide more exposure for your +workshop. Connecting GitHub to Zenodo is very easy, check out Zenodo's +[guide](https://help.zenodo.org/docs/github/archive-software/github-upload/) on +it. ## Setting up GoatCounter -s If you want to use GoatCounter for website visitor tracking, you need -to create a GoatCounter account and set up a new site for your website. -Adding a new site is very easy. Go into the "Settings" after logging -into your account. Under "Sites", click "Add new site" and fill in the -form with your website's unique name. You can use the auto-filled name -in the `includes/site-counter.html` file, which has the format of -"orgname-reponame" or modify your own. +s If you want to use GoatCounter for website visitor tracking, you need to +create a GoatCounter account and set up a new site for your website. Adding a +new site is very easy. Go into the "Settings" after logging into your account. +Under "Sites", click "Add new site" and fill in the form with your website's +unique name. You can use the auto-filled name in the +`includes/site-counter.html` file, which has the format of "orgname-reponame" or +modify your own. diff --git a/docs/guide/updating.qmd b/docs/guide/updating.qmd index 19993ba..35b3161 100644 --- a/docs/guide/updating.qmd +++ b/docs/guide/updating.qmd @@ -6,39 +6,36 @@ description: | order: 3 --- -One of the biggest strengths of Copier is that it allows you to easily -update your workshop with any changes that have been made to the -template since you first copied it. There are two ways to update (or -sync) an existing workshop with the latest changes from the template: -`update` and `recopy`. +One of the biggest strengths of Copier is that it allows you to easily update +your workshop with any changes that have been made to the template since you +first copied it. There are two ways to update (or sync) an existing workshop +with the latest changes from the template: `update` and `recopy`. -- Use `update` to apply template updates to your workshop without - overwriting local changes. `update` will compare the version of the - template you used when you first copied the template with the current - version of the template, and then apply the changes that are - different. This also means it won't overwrite any changes you made to - files in your current workshop, for example, if you deleted a file - that was in the template, it won't be copied back. +- Use `update` to apply template updates to your workshop without overwriting + local changes. `update` will compare the version of the template you used when + you first copied the template with the current version of the template, and + then apply the changes that are different. This also means it won't overwrite + any changes you made to files in your current workshop, for example, if you + deleted a file that was in the template, it won't be copied back. -- Use `recopy` if you want to reapply the template from scratch, which - will overwrite any changes you made to the files that were copied from - the template. This is useful if you want to reset the workshop to the - state of the template. For example, if you deleted a file but want it - back from the template or are simply curious to see if there are any - new changes that you might want to use. +- Use `recopy` if you want to reapply the template from scratch, which will + overwrite any changes you made to the files that were copied from the + template. This is useful if you want to reset the workshop to the state of the + template. For example, if you deleted a file but want it back from the + template or are simply curious to see if there are any new changes that you + might want to use. -In both cases, the commands are very similar and also use many of the -same options as the `copy` command. If you want to use the same answers -as given when you first copied the template, you can use the -`--defaults` option. Then it will only prompt you for the questions that -have changed since the last time you copied the template. +In both cases, the commands are very similar and also use many of the same +options as the `copy` command. If you want to use the same answers as given when +you first copied the template, you can use the `--defaults` option. Then it will +only prompt you for the questions that have changed since the last time you +copied the template. -```{.bash filename="Terminal"} +```bash {filename="Terminal"} uvx copier update --defaults # Or uvx copier recopy --defaults ``` -As with the `copy` command, the workshop needs to be tracked by Git and -must be in a clean state (no changes) for the `update` and `recopy` -commands to work. +As with the `copy` command, the workshop needs to be tracked by Git and must be +in a clean state (no changes) for the `update` and `recopy` commands to work. diff --git a/docs/guide/using.qmd b/docs/guide/using.qmd index 816c78e..f4c2d58 100644 --- a/docs/guide/using.qmd +++ b/docs/guide/using.qmd @@ -6,46 +6,44 @@ description: | order: 2 --- -This guide walks through how to use this template to create a new -workshop or apply it to an existing workshop. +This guide walks through how to use this template to create a new workshop or +apply it to an existing workshop. ## Creating a new workshop -You can use this template to create a new workshop with a standard set -of files and folders, as well as all the features and configurations to -make it easier to build your workshop smoothly and effectively. First, -open a terminal and run the following command: +You can use this template to create a new workshop with a standard set of files +and folders, as well as all the features and configurations to make it easier to +build your workshop smoothly and effectively. First, open a terminal and run the +following command: -```{.bash filename="Terminal"} +```bash {filename="Terminal"} uvx copier copy gh:rostools/template-workshop path/to/WORKSHOP-NAME ``` The `copy` command uses the template on GitHub (`gh:`) at the -`rostools/template-workshop` location. The `path/to/` is the location -where you'd like the new workshop to be created and `WORKSHOP-NAME` is -the name you want to give for the new workshop's directory and (ideally) -the GitHub repository for the workshop. The name should be something -short and meaningful, ideally lowercase, with `-` instead of spaces, and -no special characters. +`rostools/template-workshop` location. The `path/to/` is the location where +you'd like the new workshop to be created and `WORKSHOP-NAME` is the name you +want to give for the new workshop's directory and (ideally) the GitHub +repository for the workshop. The name should be something short and meaningful, +ideally lowercase, with `-` instead of spaces, and no special characters. ## Applying to an existing workshop -If you want to use this template on an existing workshop, you can use -the `copy` command of `copier` just like above to apply the template to -the existing workshop. This will add all the template's files and -configurations to the existing workshop. +If you want to use this template on an existing workshop, you can use the `copy` +command of `copier` just like above to apply the template to the existing +workshop. This will add all the template's files and configurations to the +existing workshop. -```{.bash filename="Terminal"} +```bash {filename="Terminal"} uvx copier copy gh:rostools/template-workshop path/to/EXISTING-WORKSHOP ``` -See the comment above in the "Creating a new workshop" section about the -naming of the existing workshop directory. It will go through a series -of prompts, as in the case of creating a new workshop, including asking -if you want to overwrite existing files. +See the comment above in the "Creating a new workshop" section about the naming +of the existing workshop directory. It will go through a series of prompts, as +in the case of creating a new workshop, including asking if you want to +overwrite existing files. ::: callout-note -To use the `copy` command, the existing workshop needs to be tracked by -Git and in a clean state (no changes have been made in the working -directory). +To use the `copy` command, the existing workshop needs to be tracked by Git and +in a clean state (no changes have been made in the working directory). ::: diff --git a/docs/includes/_badges.qmd b/docs/includes/_badges.qmd index 3aad20f..bfcaffe 100644 --- a/docs/includes/_badges.qmd +++ b/docs/includes/_badges.qmd @@ -1,10 +1,16 @@ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16979956.svg)](https://doi.org/10.5281/zenodo.16979956) [![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true.svg)](https://github.com/copier-org/copier) -[![GitHub License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) -[![GitHub Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) +[![GitHub +License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) +[![GitHub +Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) [![Test](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/test.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/test.yml) -[![Build website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) +[![Build +website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) [![CodeQL](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/github-code-scanning/codeql) -[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) +[![pre-commit.ci +status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) [![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Project Status: Active -- The project has reached a stable, usable state and +is being actively +developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) diff --git a/index.qmd b/index.qmd index ad8b07f..2d75119 100644 --- a/index.qmd +++ b/index.qmd @@ -2,34 +2,33 @@ {{< include /docs/includes/_badges.qmd >}} -This is a template for creating a new workshop with the intent of making -it an open educational resource (OVER). Use this template to quickly get -started with a new workshop with all the necessary files and -configurations in place, including for developing the workshop. +This is a template for creating a new workshop with the intent of making it an +open educational resource (OVER). Use this template to quickly get started with +a new workshop with all the necessary files and configurations in place, +including for developing the workshop. ## Features -There are four sets of features included in this template, those for -general workshops, those for R workshops, and those for general or R -workshops developed within rostools. These are the features for the -general workshops: +There are four sets of features included in this template, those for general +workshops, those for R workshops, and those for general or R workshops developed +within rostools. These are the features for the general workshops: -- Uses [Quarto](https://quarto.org/) for the workshop content, allowing - for easy integration of code, text, and figures. -- Includes a [justfile](https://just.systems/man/en/) for managing - common tasks like building the workshop and running checks. -- Uses [typos](https://github.com/crate-ci/typos) to check for common - spelling mistakes. -- Uses a [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) - license for the workshop content. -- Run checks with with [pre-commit](https://pre-commit.com/) hooks to - ensure consistent formatting and style across the project. It includes - checks for credentials, typos, and file formatting. -- Includes [GitHub Actions](https://docs.github.com/en/actions) for - continuous integration, testing, and delivery for running checks, - formatting, releasing, and building the website. -- Uses [Netlify](https://www.netlify.com/) for hosting the workshop - website or GitHub Pages if you prefer to host it there. +- Uses [Quarto](https://quarto.org/) for the workshop content, allowing for easy + integration of code, text, and figures. +- Includes a [justfile](https://just.systems/man/en/) for managing common tasks + like building the workshop and running checks. +- Uses [typos](https://github.com/crate-ci/typos) to check for common spelling + mistakes. +- Uses a [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) license for + the workshop content. +- Run checks with with [pre-commit](https://pre-commit.com/) hooks to ensure + consistent formatting and style across the project. It includes checks for + credentials, typos, and file formatting. +- Includes [GitHub Actions](https://docs.github.com/en/actions) for continuous + integration, testing, and delivery for running checks, formatting, releasing, + and building the website. +- Uses [Netlify](https://www.netlify.com/) for hosting the workshop website or + GitHub Pages if you prefer to host it there. - Includes an [EditorConfig](https://editorconfig.org/) file to ensure consistent formatting across different editors. - High level, system and program management with @@ -40,40 +39,37 @@ general workshops: - [`.zenodo.json`](https://help.zenodo.org/docs/github/describe-software/zenodo-json/) file for citation information, that provides Zenodo with the necessary metadata to create a DOI for the workshop. -- Includes a [GoatCounter](https://www.goatcounter.com/) file for - website visitor tracking, which is privacy-friendly and does not use - cookies. That means it doesn't need a GDPR notice as no personal data - is collected. -- Checks URLs with [Lychee](https://lychee.cli.rs) to ensure that URLs - are not broken. -- Uses [rumdl](https://rumdl.dev/) to format Markdown files in a - consistent way. +- Includes a [GoatCounter](https://www.goatcounter.com/) file for website + visitor tracking, which is privacy-friendly and does not use cookies. That + means it doesn't need a GDPR notice as no personal data is collected. +- Checks URLs with [Lychee](https://lychee.cli.rs) to ensure that URLs are not + broken. +- Uses [rumdl](https://rumdl.dev/) to format Markdown files in a consistent way. - Includes [Dependabot](https://docs.github.com/en/code-security/tutorials/secure-your-dependencies/dependabot-quickstart-guide) configuration for automatically keeping dependencies up to date. For R-specific workshops, the additional feature is: -- For R projects, uses [Air](https://posit-dev.github.io/air/) to format - and check R code. +- For R projects, uses [Air](https://posit-dev.github.io/air/) to format and + check R code. These are additional features for workshops developed within rostools: -- GitHub workflows for automatically adding Pull Requests and Issues to - a project board. -- Uses the - [`rostools-theme`](https://github.com/rostools/rostools-theme) Quarto +- GitHub workflows for automatically adding Pull Requests and Issues to a + project board. +- Uses the [`rostools-theme`](https://github.com/rostools/rostools-theme) Quarto extension for a standard appearance across workshops. - Automated Git tagging and GitHub releases with [commitizen](https://decisions.seedcase-project.org/why-semantic-release-with-commitizen/) - that are based on messages following - [Conventional Commits](https://decisions.seedcase-project.org/why-conventional-commits/). + that are based on messages following [Conventional + Commits](https://decisions.seedcase-project.org/why-conventional-commits/). ## Want to contribute? -We would love your feedback or contributions! Head over to our -[GitHub repository]({{< meta links.github >}}) to share your ideas or -contribute code. Your input makes us better! +We would love your feedback or contributions! Head over to our [GitHub +repository]({{< meta links.github >}}) to share your ideas or contribute code. +Your input makes us better! ### Contributors diff --git a/template/404.qmd b/template/404.qmd index f28249f..767f5d4 100644 --- a/template/404.qmd +++ b/template/404.qmd @@ -2,5 +2,5 @@ title: "The page you are looking for does not exist" --- -This page does not exist, go back to the [homepage](/index.qmd) or check -the URL for typos. +This page does not exist, go back to the [homepage](/index.qmd) or check the URL +for typos. diff --git a/template/CODE_OF_CONDUCT.md b/template/CODE_OF_CONDUCT.md index 6f8f13c..22171e4 100644 --- a/template/CODE_OF_CONDUCT.md +++ b/template/CODE_OF_CONDUCT.md @@ -1,28 +1,25 @@ # Contributor Code of Conduct -As contributors and maintainers of this project, we pledge to respect -all people who contribute through reporting issues, posting suggestions, -updating any material, submitting pull requests, and other activities. +As contributors and maintainers of this project, we pledge to respect all people +who contribute through reporting issues, posting suggestions, updating any +material, submitting pull requests, and other activities. -We are committed to making participation in this project a -harassment-free experience for everyone, regardless of level of -experience, gender, gender identity and expression, sexual orientation, -disability, personal appearance, body size, race, ethnicity, age, or -religion. +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of level of experience, gender, gender +identity and expression, sexual orientation, disability, personal appearance, +body size, race, ethnicity, age, or religion. -Examples of unacceptable behavior by participants include the use of -sexual language or imagery, derogatory comments or personal attacks, -trolling, public or private harassment, insults, or other unprofessional -conduct. +Examples of unacceptable behavior by participants include the use of sexual +language or imagery, derogatory comments or personal attacks, trolling, public +or private harassment, insults, or other unprofessional conduct. -Project maintainers have the right and responsibility to remove, edit, -or reject comments, commits, code, wiki edits, issues, and other -contributions that are not aligned to this Code of Conduct. Project -maintainers who do not follow the Code of Conduct may be removed from -the project team. +Project maintainers have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct. Project maintainers who do not follow the +Code of Conduct may be removed from the project team. -Instances of abusive, harassing, or otherwise unacceptable behavior may -be reported by opening an issue or contacting one or more of the project +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by opening an issue or contacting one or more of the project maintainers. This Code of Conduct is adapted from the Contributor Covenant diff --git a/template/README.qmd b/template/README.qmd index e89b021..994fe9d 100644 --- a/template/README.qmd +++ b/template/README.qmd @@ -10,59 +10,56 @@ format: gfm -This repository contains the lesson, lecture, and assignment material -for the workshop, including the website source files and other -associated workshop administration and development files. For more -detail on the workshop, check out the -[welcome page]({{< meta links.site >}}). +This repository contains the lesson, lecture, and assignment material for the +workshop, including the website source files and other associated workshop +administration and development files. For more detail on the workshop, check out +the [welcome page]({{< meta links.site >}}). ::: callout-tip This workshop repository was generated from the -[`template-workshop`](https://github.com/rostools/template-workshop) -rostools template. +[`template-workshop`](https://github.com/rostools/template-workshop) rostools +template. ::: ## Instructional Design -The lectures and lessons in this workshop are designed to be presented -primarily with a participatory live-coding approach. This involves an -teacher typing and running code in an editor or similar platform in -front of the class, while the class follows along using their own -computers. Exercises are interspersed in the lesson material, allowing -participants to collaboratively work on smaller coding problems for a -few minutes. All lesson materials are provided ahead of time on the -workshop website for participants to refer to during lectures. +The lectures and lessons in this workshop are designed to be presented primarily +with a participatory live-coding approach. This involves an teacher typing and +running code in an editor or similar platform in front of the class, while the +class follows along using their own computers. Exercises are interspersed in the +lesson material, allowing participants to collaboratively work on smaller coding +problems for a few minutes. All lesson materials are provided ahead of time on +the workshop website for participants to refer to during lectures. ## Lesson content The teaching material is found mainly in these locations: - `index.Rmd`: Contains the overview of the workshop. -- `overview/` folder: Contains the files that give an overview to the - workshop, such as the syllabus and schedule. -- `pre-workshop/`: Contains the files needed before the workshop, like - the pre-workshop tasks. -- `sessions/`: Contains the files used during the workshop (e.g. - code-along material). -- `appendix/`: Contains the files used to support the workshop, such as - code of conduct, changelog, contributing guides, and instructions for - teachers. -- `slides/`: Contains the lecture slides that are rendered into HTML - slides from Markdown. - -The website is generated with [Quarto](https://quarto.org/), so it -follows the file and folder structure conventions from that package. +- `overview/` folder: Contains the files that give an overview to the workshop, + such as the syllabus and schedule. +- `pre-workshop/`: Contains the files needed before the workshop, like the + pre-workshop tasks. +- `sessions/`: Contains the files used during the workshop (e.g. code-along + material). +- `appendix/`: Contains the files used to support the workshop, such as code of + conduct, changelog, contributing guides, and instructions for teachers. +- `slides/`: Contains the lecture slides that are rendered into HTML slides from + Markdown. + +The website is generated with [Quarto](https://quarto.org/), so it follows the +file and folder structure conventions from that package. ## Contributing -If you are interested in contributing to the workshop material, please -refer to the [contributing guidelines](CONTRIBUTING.md). For guidelines -on how to be a helper or teacher, check out the -[For teachers](https://guides.rostools.org/instructors) page. +If you are interested in contributing to the workshop material, please refer to +the [contributing guidelines](CONTRIBUTING.md). For guidelines on how to be a +helper or teacher, check out the [For +teachers](https://guides.rostools.org/instructors) page. -Please note that the project is released with a -[Contributor Code of Conduct](CODE_OF_CONDUCT.md). By contributing to or -being involved in this project, you agree to abide by its terms. +Please note that the project is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By contributing to or being involved in this +project, you agree to abide by its terms. @@ -78,12 +75,11 @@ This project is licensed under the [CC-BY-4.0 License](LICENSE.md). ## Re-use -The workshop is largely designed to be taught in the order given, as -each session builds off of the previous ones. The easiest way to use -this material is to use it as-is, making use of the tips and -instructions found throughout this page. The only thing you might want -to make as your own would be the slides, however, they are also good -enough to use on their own too. +The workshop is largely designed to be taught in the order given, as each +session builds off of the previous ones. The easiest way to use this material is +to use it as-is, making use of the tips and instructions found throughout this +page. The only thing you might want to make as your own would be the slides, +however, they are also good enough to use on their own too. To help with general admin tasks of running the workshop, there is the [samwise](https://github.com/rostools/samwise) R package. diff --git a/template/appendix/for-teachers.qmd b/template/appendix/for-teachers.qmd index da07256..68833e0 100644 --- a/template/appendix/for-teachers.qmd +++ b/template/appendix/for-teachers.qmd @@ -1,8 +1,8 @@ # For teachers {#sec-for-teachers} A more general guide to teaching or helping is found on the -[Guides](https://guides.rostools.org/) website. This page has -information relevant specifically to this workshop. +[Guides](https://guides.rostools.org/) website. This page has information +relevant specifically to this workshop. -- For created teams, assign one teacher or helper to each group to help - them specifically during the final group project. +- For created teams, assign one teacher or helper to each group to help them + specifically during the final group project. diff --git a/template/includes/_badges.qmd b/template/includes/_badges.qmd index 443751e..0bebe3c 100644 --- a/template/includes/_badges.qmd +++ b/template/includes/_badges.qmd @@ -1,8 +1,14 @@ [![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true.svg)](https://github.com/copier-org/copier) -[![GitHub License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) -[![GitHub Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) -[![Build website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) -[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) +[![GitHub +License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) +[![GitHub +Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) +[![Build +website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) +[![pre-commit.ci +status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) [![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) -[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Project Status: Active -- The project has reached a stable, usable state and +is being actively +developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) diff --git a/template/includes/_star-us.qmd b/template/includes/_star-us.qmd index 2254979..f7071d3 100644 --- a/template/includes/_star-us.qmd +++ b/template/includes/_star-us.qmd @@ -1,9 +1,8 @@ ::: {.callout-tip appearance="minimal"} ## Do you find this workshop material useful? -If yes, please consider "starring" our -[GitHub repository]({{< meta links.github >}}). Starring the repository -will save it to your list of saved repositories, so it's easy for you to -find again later. As a plus, it helps give our project more visibility -:star2: +If yes, please consider "starring" our [GitHub +repository]({{< meta links.github >}}). Starring the repository will save it to +your list of saved repositories, so it's easy for you to find again later. As a +plus, it helps give our project more visibility :star2: ::: diff --git a/template/includes/_survey.qmd b/template/includes/_survey.qmd index ab5ed5d..9ee2671 100644 --- a/template/includes/_survey.qmd +++ b/template/includes/_survey.qmd @@ -1,2 +1,3 @@ -[Feedback survey! :tada:]({{< meta surveys.feedback >}}){.btn +[Feedback survey! +:tada:]({{< meta surveys.feedback >}}){.btn .btn-primary role="button"} diff --git a/template/overview/is-this-for-you.qmd b/template/overview/is-this-for-you.qmd index 0aac076..8dcb4cc 100644 --- a/template/overview/is-this-for-you.qmd +++ b/template/overview/is-this-for-you.qmd @@ -1,20 +1,18 @@ # Is this for you? {#sec-is-this-for-you} -To help manage expectations and develop the material for this workshop, -we make a few assumptions about *who you are* as a participant in the -workshop. +To help manage expectations and develop the material for this workshop, we make +a few assumptions about *who you are* as a participant in the workshop. We assume you can relate to one or more of the following: - TODO: List assumptions -While we have these assumptions to help focus the content of the -workshop, if you have an interest in the workshop but don't fit any of -the assumptions, *you are still welcome to attend*! We welcome everyone -until capacity has been reached. +While we have these assumptions to help focus the content of the workshop, if +you have an interest in the workshop but don't fit any of the assumptions, *you +are still welcome to attend*! We welcome everyone until capacity has been +reached. -In addition to the assumptions above, the workshop also has a fairly -focused scope, which may also help you decide if this workshop is for -you: +In addition to the assumptions above, the workshop also has a fairly focused +scope, which may also help you decide if this workshop is for you: - TODO: List of concrete tasks we will do and not do. diff --git a/template/overview/learning-design.qmd b/template/overview/learning-design.qmd index e345f63..e71938d 100644 --- a/template/overview/learning-design.qmd +++ b/template/overview/learning-design.qmd @@ -2,106 +2,97 @@ # Learning design {#sec-learning-design} -This workshop is designed using the science of learning. Learning is -when new content gets incorporated into long-term storage in the brain -in a way that it can be later retrieved. Some of the best ways to enable -learning is to do "active learning" by engaging with the material, -practicing retrieving what was just covered, repeatedly being exposed to -the content, linking the new information with what you already know, and -explaining it to someone else. - -We use a variety of activities to target the different "pathways" of -learning. A big part of learning is being engaged in the *process* of -learning, not just learning the content itself. So to help you be -engaged in your own learning, we want to involve you in the reasons -*why* we do the things we do during this workshop. +This workshop is designed using the science of learning. Learning is when new +content gets incorporated into long-term storage in the brain in a way that it +can be later retrieved. Some of the best ways to enable learning is to do +"active learning" by engaging with the material, practicing retrieving what was +just covered, repeatedly being exposed to the content, linking the new +information with what you already know, and explaining it to someone else. + +We use a variety of activities to target the different "pathways" of learning. A +big part of learning is being engaged in the *process* of learning, not just +learning the content itself. So to help you be engaged in your own learning, we +want to involve you in the reasons *why* we do the things we do during this +workshop. Throughout the workshop, we use these practices to support learning. ## Clear learning goals and a strong narrative -The learning goals and the narrative are tightly connected in this -workshop. Learning is easier when you have a better idea of where you -are going, where you are relative to the end goal, and what to expect -along the way. +The learning goals and the narrative are tightly connected in this workshop. +Learning is easier when you have a better idea of where you are going, where you +are relative to the end goal, and what to expect along the way. ## "Code-alongs" as the main activity "Code-alongs" is when the teacher types on their computer that is on the -projector and explains what it means as you also type along with them. -The connection between using the hands and doing something tangible -helps reinforce learning. It also helps the teachers to go slower as we -have to both explain and type things out. This helps you learn better. -"Less is more" works very well with learning. +projector and explains what it means as you also type along with them. The +connection between using the hands and doing something tangible helps reinforce +learning. It also helps the teachers to go slower as we have to both explain and +type things out. This helps you learn better. "Less is more" works very well +with learning. ## Retrieval practice with hands-on exercises -Hands-on exercises reinforce what was just taught through retrieval -practice and repetition. It gives you a chance to engage with the -material and the space to try it out on your own. This helps you form a -better sense of how to do it yourself. +Hands-on exercises reinforce what was just taught through retrieval practice and +repetition. It gives you a chance to engage with the material and the space to +try it out on your own. This helps you form a better sense of how to do it +yourself. ## Linking new information with existing knowledge with discussion activities -Discussion activities encourage linking what you already know and do in -your work with the new information. Because humans are social beings, we -also tend to learn better when there is some social aspect to it. For -example, explaining something to someone else is one of the best ways to -learn, as nicely expressed in the quote "while we teach, we learn" from -the Roman philosopher Seneca. +Discussion activities encourage linking what you already know and do in your +work with the new information. Because humans are social beings, we also tend to +learn better when there is some social aspect to it. For example, explaining +something to someone else is one of the best ways to learn, as nicely expressed +in the quote "while we teach, we learn" from the Roman philosopher Seneca. ## Minimal use of lectures -Lectures, while extremely common, are forms of information sharing with -the lowest rates of learning. In this workshop, we use reading tasks -instead, so you can go at your pace, re-read things you may not -understand, and take notes, all of which support learning. To help -reinforce what you just read, the teacher will briefly summarise and -emphasise key points after reading tasks, to repeat the main points and -target another part of the brain (the auditory pathway). +Lectures, while extremely common, are forms of information sharing with the +lowest rates of learning. In this workshop, we use reading tasks instead, so you +can go at your pace, re-read things you may not understand, and take notes, all +of which support learning. To help reinforce what you just read, the teacher +will briefly summarise and emphasise key points after reading tasks, to repeat +the main points and target another part of the brain (the auditory pathway). ## Frequent breaks and variation in activities -Breaks are how your brain can recharge and refocus. The brain is only -able to effectively focus on one thing at a time in 30-50 minute blocks -of time. That's why we mix together code-alongs, exercises, discussions, -and reading to give your brain some variation. Having an explicit break, -even 5 minutes, is enough for the brain to better process and store what -was covered. +Breaks are how your brain can recharge and refocus. The brain is only able to +effectively focus on one thing at a time in 30-50 minute blocks of time. That's +why we mix together code-alongs, exercises, discussions, and reading to give +your brain some variation. Having an explicit break, even 5 minutes, is enough +for the brain to better process and store what was covered. ## Easily accessible material that is online, always -All the material is online on this website, so that it is easy for you -to go back to after the workshop. This builds the repetition and -retrieval practice part of learning. Our brains also get easily -distracted, which is completely normal. So if you get distracted during -the workshop, you can simply go to the material and get caught up with -where we are. We also make sure to follow the material on the website -closely, so that it is easier for you to follow along. +All the material is online on this website, so that it is easy for you to go +back to after the workshop. This builds the repetition and retrieval practice +part of learning. Our brains also get easily distracted, which is completely +normal. So if you get distracted during the workshop, you can simply go to the +material and get caught up with where we are. We also make sure to follow the +material on the website closely, so that it is easier for you to follow along. ## A safe and supportive environment -Mental safety in a supportive environment is critical for effective -learning. It puts the brain into a more relaxed state that allows for -optimal processing and ultimately learning. That's why we try to -explicitly create that space, for example with the use of our Code of -Conduct. +Mental safety in a supportive environment is critical for effective learning. It +puts the brain into a more relaxed state that allows for optimal processing and +ultimately learning. That's why we try to explicitly create that space, for +example with the use of our Code of Conduct. ## Using origami hats to ask for help -Asking for help can feel difficult, especially when you are learning and -are unsure about something. To make it easier and feel safer, we use -origami hats (or stickies) to show how everyone is doing. If you need -help, you put up the "help" hat (usually orange) and a helper will come -to you as soon as possible. If not, you can put up a "all good" hat -(usually blue) to let us know you are following along. Since we often -have several helpers, you usually won’t wait long. This simple system -lets you ask for help without interrupting the teacher or drawing -attention, so you can keep following along while you wait. Our goal is -to make getting help easier and more comfortable. +Asking for help can feel difficult, especially when you are learning and are +unsure about something. To make it easier and feel safer, we use origami hats +(or stickies) to show how everyone is doing. If you need help, you put up the +"help" hat (usually orange) and a helper will come to you as soon as possible. +If not, you can put up a "all good" hat (usually blue) to let us know you are +following along. Since we often have several helpers, you usually won't wait +long. This simple system lets you ask for help without interrupting the teacher +or drawing attention, so you can keep following along while you wait. Our goal +is to make getting help easier and more comfortable. ## Being involved in the learning process -Now you know a bit more about the thoughts behind how we've designed -this workshop to really try to support and enable your own learning! -:tada: :grin: +Now you know a bit more about the thoughts behind how we've designed this +workshop to really try to support and enable your own learning! :tada: :grin: diff --git a/template/overview/schedule.qmd b/template/overview/schedule.qmd index 38ac81c..7db33ae 100644 --- a/template/overview/schedule.qmd +++ b/template/overview/schedule.qmd @@ -6,28 +6,26 @@ format: # Schedule {#sec-schedule} -The workshop is structured as a series of participatory live-coding -sessions interspersed with hands-on exercises and group work, using -either a practice dataset or some other real-world dataset. There are -some lectures given, mainly at the start and end of the workshop. The -general schedule outline is shown in the below table. This is not a -fixed schedule of the timings of each session---some may be shorter and -others may be longer. Instead, it is meant to be an approximate guide -and overview. +The workshop is structured as a series of participatory live-coding sessions +interspersed with hands-on exercises and group work, using either a practice +dataset or some other real-world dataset. There are some lectures given, mainly +at the start and end of the workshop. The general schedule outline is shown in +the below table. This is not a fixed schedule of the timings of each +session---some may be shorter and others may be longer. Instead, it is meant to +be an approximate guide and overview. ::: panel-tabset ## Day 1 {.unnumbered} -| Time | Session topic | -|:------|:----------------------------------------------------------------------------------------| -| 9:30 | {{< fa mug-hot >}} Arrival; Coffee and light breakfast | -| 10:00 | {{< fa person-chalkboard >}} [Introduction to the workshop](/sessions/introduction.qmd) | -| 10:30 | {{< fa laptop-code >}} TBD | -| 12:20 | {{< fa comment-dots >}} [End of session short survey]() | -| 12:30 | {{< fa utensils >}} Lunch | -| 13:15 | {{< fa laptop-code >}} TBD | -| 14:45 | {{< fa mug-hot >}} Break with coffee and snacks | -| 15:00 | {{< fa laptop-code >}} TBD | -| 16:30 | {{< fa comment-dots >}} [End of session short survey]() | - + | Time | Session topic | + | :---- | :-------------------------------------------------------------------------------------- | + | 9:30 | {{< fa mug-hot >}} Arrival; Coffee and light breakfast | + | 10:00 | {{< fa person-chalkboard >}} [Introduction to the workshop](/sessions/introduction.qmd) | + | 10:30 | {{< fa laptop-code >}} TBD | + | 12:20 | {{< fa comment-dots >}} [End of session short survey]() | + | 12:30 | {{< fa utensils >}} Lunch | + | 13:15 | {{< fa laptop-code >}} TBD | + | 14:45 | {{< fa mug-hot >}} Break with coffee and snacks | + | 15:00 | {{< fa laptop-code >}} TBD | + | 16:30 | {{< fa comment-dots >}} [End of session short survey]() | ::: diff --git a/template/overview/syllabus.qmd b/template/overview/syllabus.qmd index 410d072..b0c7591 100644 --- a/template/overview/syllabus.qmd +++ b/template/overview/syllabus.qmd @@ -2,9 +2,8 @@ TODO: Include description and overall introduction of workshop -This workshop lasts TODO: Time and is split into the following sessions, -listed in the [schedule](/overview/schedule.qmd), which will be covered -in order: +This workshop lasts TODO: Time and is split into the following sessions, listed +in the [schedule](/overview/schedule.qmd), which will be covered in order: - [Introduction to the workshop](/sessions/introduction.qmd) - [TODO: Session title](/sessions/session.qmd) @@ -16,8 +15,8 @@ The overall aim of this workshop is to enable you to: 1. -Broken down into specific objectives for each session, we've designed -the workshop to enable you to do the following: +Broken down into specific objectives for each session, we've designed the +workshop to enable you to do the following: [**TODO: Session title**](/sessions/session.qmd) diff --git a/template/pre-workshop/code-of-conduct.qmd b/template/pre-workshop/code-of-conduct.qmd index ebcb90c..9b4d09a 100644 --- a/template/pre-workshop/code-of-conduct.qmd +++ b/template/pre-workshop/code-of-conduct.qmd @@ -2,91 +2,86 @@ # Code of conduct {#sec-code-of-conduct} -Learning happens when we feel safe and supported. Since we want you to -learn during this workshop, we want you to feel safe and supported. We -also want all learners to have an enjoyable and fulfilling experience -while participating in this workshop. So we expect all learners to show -respect, kindness, and courtesy to other learners throughout the whole -workshop and to help create a positive and safe learning environment. - -While most people and (sub-)cultures have an implicit, assumed set of -practices and expectations for behaviour, we believe strongly in -effective and clear communication. This includes making what is normally -implicit expectations to instead be explicit expectations. +Learning happens when we feel safe and supported. Since we want you to learn +during this workshop, we want you to feel safe and supported. We also want all +learners to have an enjoyable and fulfilling experience while participating in +this workshop. So we expect all learners to show respect, kindness, and courtesy +to other learners throughout the whole workshop and to help create a positive +and safe learning environment. + +While most people and (sub-)cultures have an implicit, assumed set of practices +and expectations for behaviour, we believe strongly in effective and clear +communication. This includes making what is normally implicit expectations to +instead be explicit expectations. Teachers and helpers will uphold and embody this code in all spaces and -activities of the workshop, and we expect you as the learner to do the -same. In fact, by participating in this workshop, you indicate that you -agree to follow these explicit expectations. We have this code of -conduct to communicate to you that we really value and want to nurture a -space that encourages and enhances learning. Otherwise, why would we -have a workshop if you can't or aren't able to effectively learn -anything from it! :zany_face: +activities of the workshop, and we expect you as the learner to do the same. In +fact, by participating in this workshop, you indicate that you agree to follow +these explicit expectations. We have this code of conduct to communicate to you +that we really value and want to nurture a space that encourages and enhances +learning. Otherwise, why would we have a workshop if you can't or aren't able to +effectively learn anything from it! :zany_face: ## Expected behavior We want a welcoming, supportive, safe, and fun environment not only for -ourselves as teachers and helpers, but also for all learners, regardless -of background and identity. This means that we do not tolerate behaviour -that is disrespectful to any of our teachers, helpers, or learners (see -below for unacceptable behaviour). +ourselves as teachers and helpers, but also for all learners, regardless of +background and identity. This means that we do not tolerate behaviour that is +disrespectful to any of our teachers, helpers, or learners (see below for +unacceptable behaviour). -We encourage the following kinds of behaviours in all interactions -during this workshop that will foster a positive and professional -learning environment: +We encourage the following kinds of behaviours in all interactions during this +workshop that will foster a positive and professional learning environment: - Show kindness, courtesy, and respect towards other workshop members. -- All interactions should be professional regardless of platform: either - online or in-person. -- Be aware of your words by using welcoming and inclusive language. - Words matter, a lot! +- All interactions should be professional regardless of platform: either online + or in-person. +- Be aware of your words by using welcoming and inclusive language. Words + matter, a lot! - Be respectful to different viewpoints and experiences. - Gracefully accept constructive criticism. - Focus on what is best for everyone in the workshop. ## Unacceptable behavior -While we assume you will not do these behaviours, we want to clearly -communicate what unacceptable behaviour is. It is any behaviour, as -actions or words, that excludes, intimidates, or causes discomfort to -others. We do not tolerate discrimination or harassment based on -characteristics that include, though are not limited to, gender identity -and expression, sexual orientation, disability, physical appearance, -body size, citizenship, nationality, ethnic or social origin, pregnancy, -familial status, veteran status, genetic information, religion or belief -(or lack thereof), membership of a national minority, property, age, -education, socio-economic status, technical choices, and experience -level. We of course also don't tolerate verbally or physically violent -behaviour towards others. +While we assume you will not do these behaviours, we want to clearly communicate +what unacceptable behaviour is. It is any behaviour, as actions or words, that +excludes, intimidates, or causes discomfort to others. We do not tolerate +discrimination or harassment based on characteristics that include, though are +not limited to, gender identity and expression, sexual orientation, disability, +physical appearance, body size, citizenship, nationality, ethnic or social +origin, pregnancy, familial status, veteran status, genetic information, +religion or belief (or lack thereof), membership of a national minority, +property, age, education, socio-economic status, technical choices, and +experience level. We of course also don't tolerate verbally or physically +violent behaviour towards others. Examples of unacceptable behavior includes: -- Written or verbal comments that exclude people on the basis of - membership of any specific group. +- Written or verbal comments that exclude people on the basis of membership of + any specific group. - The display of sexual or violent images. - Unwelcome sexual attention, advances, and/or physical contact. - Sustained disruption of workshop sessions or communications. - Insults or put downs. -- Sexist, racist, homophobic, transphobic, ableist, or exclusionary - jokes. +- Sexist, racist, homophobic, transphobic, ableist, or exclusionary jokes. ## Consequences of unacceptable behavior -Learners who are asked, either in person or online, to stop any -inappropriate behavior are expected to comply immediately. If a learners -engages in behaviour that violates this code of conduct, the organizers, -teachers, or helpers may take any action they deem appropriate, -including warning the offender or removing them from the workshop. +Learners who are asked, either in person or online, to stop any inappropriate +behavior are expected to comply immediately. If a learners engages in behaviour +that violates this code of conduct, the organizers, teachers, or helpers may +take any action they deem appropriate, including warning the offender or +removing them from the workshop. -If you feel in any way unsafe or mistreated, you may contact us -privately---all communication is confidential. +If you feel in any way unsafe or mistreated, you may contact us privately---all +communication is confidential. -Thank you for helping make this a welcoming, friendly workshop for all -:smile: +Thank you for helping make this a welcoming, friendly workshop for all :smile: ::: {.callout-note appearance="default"} -*Acknowledgements*: Large portions of this code of conduct were taken -and modified from other codes of conduct, specifically -[Software Carpentry](https://docs.carpentries.org/policies/coc/) and +*Acknowledgements*: Large portions of this code of conduct were taken and +modified from other codes of conduct, specifically [Software +Carpentry](https://docs.carpentries.org/policies/coc/) and [UofTCoders](https://github.com/UofTCoders/studyGroup/blob/gh-pages/codeOfConduct.md). ::: diff --git a/template/pre-workshop/survey.qmd b/template/pre-workshop/survey.qmd index 981c042..aa3c4f1 100644 --- a/template/pre-workshop/survey.qmd +++ b/template/pre-workshop/survey.qmd @@ -1,17 +1,18 @@ # Survey {#sec-survey} -We have a [Code of Conduct](/pre-workshop/code-of-conduct.qmd). If you -haven't read it, **read it now**. The survey involves a question about -Conduct. We want to make sure this workshop is a supportive and safe -environment for learning, so this Code of Conduct is quite important. +We have a [Code of Conduct](/pre-workshop/code-of-conduct.qmd). If you haven't +read it, **read it now**. The survey involves a question about Conduct. We want +to make sure this workshop is a supportive and safe environment for learning, so +this Code of Conduct is quite important. -If you haven't read the sections under "Workshop overview" and -"Pre-workshop tasks", **please read them now**. +If you haven't read the sections under "Workshop overview" and "Pre-workshop +tasks", **please read them now**. -You're almost done. Please fill out the pre-workshop survey to finish -this section: +You're almost done. Please fill out the pre-workshop survey to finish this +section: -[Pre-workshop survey :tada:]({{< meta surveys.pre-workshop >}}){.btn +[Pre-workshop survey +:tada:]({{< meta surveys.pre-workshop >}}){.btn .btn-primary role="button"} See you at the workshop! :wave: diff --git a/template/sessions/conclusion.qmd b/template/sessions/conclusion.qmd index 7493985..45f5ea7 100644 --- a/template/sessions/conclusion.qmd +++ b/template/sessions/conclusion.qmd @@ -13,6 +13,6 @@ ::: {.callout-note collapse="true"} ## Teacher note -The slides contain speaking notes that you can view by pressing 'S' on -the keyboard. +The slides contain speaking notes that you can view by pressing 'S' on the +keyboard. ::: diff --git a/template/sessions/introduction.qmd b/template/sessions/introduction.qmd index 59221fc..a4b7a4f 100644 --- a/template/sessions/introduction.qmd +++ b/template/sessions/introduction.qmd @@ -13,8 +13,8 @@ ::: {.callout-note collapse="true"} ## Teacher note -The slides contain speaking notes that you can view by pressing 'S' on -the keyboard. +The slides contain speaking notes that you can view by pressing 'S' on the +keyboard. ::: ## The Big Picture diff --git a/template/sessions/session.qmd b/template/sessions/session.qmd index 09239e5..06ce0a8 100644 --- a/template/sessions/session.qmd +++ b/template/sessions/session.qmd @@ -18,7 +18,7 @@ TODO: Reading text ## :technologist: Exercise: Title -**Time: ~NUM minutes.** +**Time: \~NUM minutes.** Text @@ -26,13 +26,13 @@ Text ## :speech_balloon: Discussion activity: Title -**Time: ~Num minutes.** +**Time: \~Num minutes.** Text ## :book: Reading task: Title -**Time: ~Num minutes.** +**Time: \~Num minutes.** Text From e94e7ec90773abdf3fcc484644914773c26fcd74 Mon Sep 17 00:00:00 2001 From: Daniel Mazhari-Jensen Date: Mon, 10 Aug 2026 10:54:56 +0200 Subject: [PATCH 3/3] =?UTF-8?q?build:=20=F0=9F=91=B7=20remove-typos-from-b?= =?UTF-8?q?uild-workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/build-website.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.github/workflows/build-website.yml b/.github/workflows/build-website.yml index d41da1b..0582ec2 100644 --- a/.github/workflows/build-website.yml +++ b/.github/workflows/build-website.yml @@ -28,9 +28,6 @@ jobs: - name: Check out repository uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Spell check repo - uses: crate-ci/typos@bee27e3a4fd1ea2111cf90ab89cd076c870fce14 # v1.48.0 - - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0