Full review of tutorials-early website

.github/workflows/README.md

@@ -96,7 +96,7 @@ are okay.
 
 This update is run ~~weekly or~~ on demand.
 
-### 03 Maintain: Update Pacakge Cache (update-cache.yaml)
+### 03 Maintain: Update Package Cache (update-cache.yaml)
 
 For lessons that have generated content, we use {renv} to ensure that the output
 is stable. This is controlled by a single lockfile which documents the packages

.github/workflows/lint.yaml

@@ -0,0 +1,42 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+name: lint
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    env:
+      GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      RENV_PATHS_ROOT: ~/.local/share/renv/
+    steps:
+      - uses: actions/checkout@v3
+
+      - uses: r-lib/actions/setup-r@v2
+        with:
+          use-public-rspm: true
+
+      - name: "Setup Lesson Engine"
+        uses: carpentries/actions/setup-sandpaper@main
+        with:
+          cache-version: ${{ secrets.CACHE_VERSION }}
+
+      - name: "Setup Package Cache"
+        uses: carpentries/actions/setup-lesson-deps@main
+        with:
+          cache-version: ${{ secrets.CACHE_VERSION }}
+
+      - uses: r-lib/actions/setup-r-dependencies@v2
+        with:
+          packages: any::lintr
+
+      - name: Lint
+        run: lintr::lint_dir("episodes")
+        shell: Rscript {0}
+        env:
+          LINTR_ERROR_ON_LINT: true

.github/workflows/sandpaper-version.txt

@@ -1 +1 @@
-0.11.12
+0.16.1

.lintr

@@ -0,0 +1,20 @@
+linters: all_linters(
+    packages = "lintr",
+    object_name_linter = NULL,
+    implicit_integer_linter = NULL,
+    brace_linter = NULL,
+    extraction_operator_linter = NULL,
+    missing_package_linter = NULL,
+    library_call_linter = NULL,
+    namespace_linter = NULL,
+    undesirable_function_linter(
+      modify_defaults(
+        default_undesirable_functions,
+        library = NULL # this is fine in Rmd files
+      )
+    ),
+   unused_import_linter(
+      allow_ns_usage = TRUE,
+      except_packages = c("bit64", "data.table", "tidyverse")
+    )
+  )

CODE_OF_CONDUCT.md

@@ -3,11 +3,13 @@ title: "Contributor Code of Conduct"
 ---
 
 As contributors and maintainers of this project,
-we pledge to follow the [The Carpentries Code of Conduct][coc].
+we pledge to follow the [The Epiverse-TRACE Code of Conduct][coc].
 
+<!--
 Instances of abusive, harassing, or otherwise unacceptable behavior
 may be reported by following our [reporting guidelines][coc-reporting].
+-->
 
+[coc-reporting]: https://forms.gle/guKqVXPk6K43jPn59
+[coc]: https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md
 
-[coc-reporting]: https://docs.carpentries.org/topic_folders/policies/incident-reporting.html
-[coc]: https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html

CONTRIBUTING.md

@@ -1,8 +1,7 @@
 ## Contributing
 
-[The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data
-Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source
-projects, and we welcome contributions of all kinds: new lessons, fixes to
+[The Epiverse-TRACE][cp-site] is an open source
+project, and we welcome contributions of all kinds: new documentation, fixes to
 existing material, bug reports, and reviews of proposed changes are all
 welcome.
 
@@ -11,7 +10,7 @@ welcome.
 By contributing, you agree that we may redistribute your work under [our
 license](LICENSE.md). In exchange, we will address your issues and/or assess
 your change proposal as promptly as we can, and help you become a member of our
-community. Everyone involved in [The Carpentries][cp-site] agrees to abide by
+community. Everyone involved in [Epiverse-TRACE][cp-site] agrees to abide by
 our [code of conduct](CODE_OF_CONDUCT.md).
 
 ### How to Contribute
@@ -32,14 +31,14 @@ introduce yourself and to meet some of our community members.
 3. If you are comfortable with Git, and would like to add or change material,
    you can submit a pull request (PR). Instructions for doing this are
    [included below](#using-github). For inspiration about changes that need to
-   be made, check out the [list of open issues][issues] across the Carpentries.
+   be made, check out the [list of open issues][issues].
 
 Note: if you want to build the website locally, please refer to [The Workbench
 documentation][template-doc].
 
 ### Where to Contribute
 
-1. If you wish to change this lesson, add issues and pull requests here.
+1. If you wish to change this tutorial, add issues and pull requests here.
 2. If you wish to change the template used for workshop websites, please refer
    to [The Workbench documentation][template-doc].
 
@@ -50,18 +49,17 @@ There are many ways to contribute, from writing new exercises and improving
 existing ones to updating or filling in the documentation and submitting [bug
 reports][issues] about things that do not work, are not clear, or are missing.
 If you are looking for ideas, please see [the list of issues for this
-repository][repo-issues], or the issues for [Data Carpentry][dc-issues],
-[Library Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects.
+repository][repo-issues].
 
 Comments on issues and reviews of pull requests are just as welcome: we are
 smarter together than we are on our own. **Reviews from novices and newcomers
 are particularly valuable**: it's easy for people who have been using these
-lessons for a while to forget how impenetrable some of this material can be, so
+tutorials for a while to forget how impenetrable some of this material can be, so
 fresh eyes are always welcome.
 
 ### What *Not* to Contribute
 
-Our lessons already contain more material than we can cover in a typical
+Our tutorials already contain more material than we can cover in a typical
 workshop, so we are usually *not* looking for more concepts or tools to add to
 them. As a rule, if you want to introduce a new idea, you must (a) estimate how
 long it will take to teach and (b) explain what you would take out to make room
@@ -70,9 +68,117 @@ second, to think hard about priorities.
 
 We are also not looking for exercises or other material that only run on one
 platform. Our workshops typically contain a mixture of Windows, macOS, and
-Linux users; in order to be usable, our lessons must run equally well on all
+Linux users; in order to be usable, our tutorials must run equally well on all
 three.
 
+### Contribution roles
+
+For a tutorial your role could be of a __Developer__, __Reviewer__, or __Maintainer__. Our goal is to keep an homogeneous package environment among Developers and Reviewers of a “feature branch” different to main. This implies that:
+
+- We will use [`sandpaper::use_package_cache()`](https://carpentries.github.io/sandpaper/reference/package_cache.html#background) in the R project.
+- The Developer will need to register the package version to use in a `renv.lock` file.
+- The Reviewer will need to restore environment defined by Developer, if needs to build the website locally.
+
+
+#### Developer:
+
+You can follow these steps:
+
+- [Update](https://carpentries.github.io/workbench/#updating) the set of workbench packages:
+
+```r
+install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
+  repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
+```
+
+To contribute with a new episode:
+
+- [Create](https://happygitwithr.com/git-branches#create-a-new-branch) a new feature branch. Write in there your contribution.
+- Create an Issue to report the start of your WIP feature branch. Add the [WIP label](https://github.com/epiverse-trace/tutorials/labels/WIP) to it. This aims to keep one contributor per feature branch. 
+- [Create](https://carpentries.github.io/sandpaper-docs/aio.html#episodes) a new episode with `sandpaper::create_episode_md("Episode Name")`
+
+If you need to work with the most recent versions of packages:
+
+- Use [`sandpaper::update_cache()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html). This will: 
+  + Fetch updates from CRAN or GitHub,
+  + Update the `renv.lock` file with package specific versions, and
+  + Update the cache. This is located in a folder called `renv/library/` in the same directory of the `renv.lock`, only visible locally.
+- Push the updated `renv.lock` file to the GitHub “development branch”.
+
+If you need to work with a specific stable version of a package:
+
+- Use [`sandpaper::pin_version()`](https://carpentries.github.io/sandpaper/articles/building-with-renv.html#pinning-specific-package-versions). This will:
+  + Update the `renv.lock` file with the specific version,
+  + Update the cache.
+- Push the updated `renv.lock` file.
+
+If you need the version of a package that is not programmatically loaded, i.e., is loaded as part of the dependency tree of an specific package:
+
+- [Create](https://carpentries.github.io/sandpaper/articles/building-with-renv.html#adding-new-packages-to-the-cache) an `episodes/install.R` file that lists the installation scripts for the packages in your lesson.
+- Run the `episodes/install.R` file to install the list of packages.
+- Run `sandpaper::update_cache()`. Before you accept the update, verify that the expected version number is listed as an update. After this, review the `renv.lock` file if this modified the file as expected. 
+
+To merge your new episodes:
+
+- Make a Pull request (PR). You can follow the stesp on [using GitHub](#using-github).
+
+#### Reviewer:
+
+You can follow these steps:
+
+- [Install](https://carpentries.github.io/workbench/#installation) the set of workbench packages:
+
+```r
+install.packages(c("sandpaper", "varnish", "pegboard", "tinkr"),
+  repos = c("https://carpentries.r-universe.dev/", getOption("repos")))
+```
+
+- [Clone](https://happygitwithr.com/new-github-first.html#new-rstudio-project-via-git) the repository or [Pull](https://www.epirhandbook.com/en/version-control-and-collaboration-with-git-and-github.html?q=github#in-rstudio-1) to update the branch to review on Rstudio.
+- [Checkout](https://happygitwithr.com/git-branches#switching-branches) or [Switch](https://rstudio.github.io/cheatsheets/html/rstudio-ide.html#version-control) to the branch to review.
+- Use [`sandpaper::manage_deps()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html) to align the packages in your cache with the ones in the `renv.lock` file (defined by the Developer).
+   - You may need to manually install certain packages used in the lesson - please check the output in case [`sandpaper::manage_deps()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html) fails. This can be resolved on a trial and error basis.
+- Render lesson with [`sandpaper::build_lesson()`](https://carpentries.github.io/sandpaper/reference/build_lesson.html). This will open an HTML tab in your browser to review. This HTML format is how the website is going to look like online.
+- Make any edit suggestion to the `.Rmd` files inside the `episodes/` folder of the branch under review. For big changes, [create an issue][issues] first.
+
+If you have issues at the Render step, follow these two steps:
+
+- Verify or wait until the branch is under Pull Request (PR) with all checks passed.
+- Access to the [`md-outputs-PR-##` branch][repo-branches] on GitHub to read the `.md` files for each episode. 
+
+Consider that:
+
+- The number `##` is equal to the PR number. 
+- `.md` files contain [generated lesson content](https://carpentries.github.io/sandpaper-docs/deployment.html) for review with knitted text, code, and figures. 
+- These `.md` files generate the `.html` of the website and look similar to how it's going to look like online.
+<!-- - Locally, after switching to the review branch in Rstudio, you can use the [Visual editor](https://posit.co/blog/exploring-rstudio-visual-markdown-editor/), or Preview it as an HTML file (which later you will need to delete).-->
+- Make any edit suggestions in the [PR online on GitHub](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request).
+
+#### Maintainer:
+
+You can follow this reference:
+
+- Update steps above from any discussion on [issues][repo-issues].
+- Review how to [maintain a Healthy Infrastructure](https://carpentries.github.io/sandpaper-docs/update.html).
+- Review how to [Automate a Pull Request](https://carpentries.github.io/sandpaper-docs/pull-request.html#automated-pull-requests).
+- Review topics on [Collaborative Lesson Development](https://carpentries.github.io/lesson-development-training/)
+
+### Writing guidelines
+
+To write a new episode, follow these guidelines
+
+- Add new `.Rmd` files to the `episode/` folder.
+- Add file name to the `config.yaml` under `episodes:` in the order you want the tutorials to appear in.
+- Add required data sets to the `episodes/data/` folder.
+- Add glossary terms to `learners/reference.md`.
+- Add commonly used links to `links.md`.
+- Add a visible callout for prerequisites at the beginning following the [ETK modules notation](https://github.com/epiverse-trace/tutorials/issues/19). 
+- Add an [introduction section](https://github.com/epiverse-trace/tutorials/issues/17) with the expected summative assessment. 
+- Add diagrams using Diagrammer with greek letters for parameters to [visually represent mathematical models](https://github.com/epiverse-trace/tutorials/issues/21).  
+- Use [callouts](https://carpentries.github.io/sandpaper-docs/instructor/component-guide.html) for complementary concepts and function arguments details.  
+  - Review how callouts need to be [coded in plain text](https://github.com/carpentries/sandpaper-docs/blob/main/learners/component-guide.md?plain=1). 
+  - Review when to use the [spoiler snipped](https://carpentries.github.io/sandpaper-docs/aio.html#use-spoilers-instead-of-floating-solution-blocks). 
+- Request a review via PR.
+
 ### Using GitHub
 
 If you choose to contribute via GitHub, you may want to look at [How to
@@ -93,19 +199,33 @@ Each lesson has a team of maintainers who review issues and pull requests or
 encourage others to do so. The maintainers are community volunteers, and have
 final say over what gets merged into the lesson.
 
+#### Rebase
+
+- If you need to get the latest commits in the `main` branch to use them in your development, we recommend rebasing your feature branch. Rebase will keep the [commit history linear](https://epiverse-trace.github.io/blueprints/git-branching-merging.html#merging-pull-requests-merge-commits-vs-squash-and-merge-vs-rebase-and-merge). First, make sure that you are the only contributor in the `feature` branch, then:
+    - In the local repository, follow all these five steps:
+      1. Switch to the `main` branch: `git checkout main`
+      2. Pull the `main` branch: `git pull`
+      3. Switch to your `feature` branch: `git checkout feature`
+      4. [Rebase](https://docs.gitlab.com/ee/topics/git/git_rebase.html) your `feature` branch onto `main` branch: `git rebase main`
+      5. Push your rebased `featured` branch using the `--force` option (this must be a forced update): `git push --force` 
+    - In the remote repository, only if you are in a PR:
+      - Update your PR branch with [Update with Rebase](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/keeping-your-pull-request-in-sync-with-the-base-branch#updating-your-pull-request-branch).
+      - To pull changes to your local repository from an updated PR branch with rebase in the remote, run: `git pull --rebase`
+    <!-- - Go to Git tab in the environments pane. Click on `Pull options` > `Pull with rebase`.-->
+
 ### Other Resources
 
-The Carpentries is a global organisation with volunteers and learners all over
+The Epiverse-TRACE is a global organisation with volunteers and learners all over
 the world. We share values of inclusivity and a passion for sharing knowledge,
-teaching and learning. There are several ways to connect with The Carpentries
-community listed at <https://carpentries.org/connect/> including via social
+teaching and learning. There are several ways to connect with The Epiverse-TRACE
+community listed at <https://github.com/epiverse-trace/> including via social
 media, slack, newsletters, and email lists. You can also [reach us by
 email][contact].
 
-[repo]: https://example.com/FIXME
-[repo-issues]: https://example.com/FIXME/issues
-[contact]: mailto:[email protected]
-[cp-site]: https://carpentries.org/
+[repo]: https://github.com/epiverse-trace/tutorials-early
+[repo-issues]: https://github.com/epiverse-trace/tutorials-early/issues
+[contact]: mailto:[email protected]
+[cp-site]: https://epiverse-trace.github.io/
 [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry
 [dc-lessons]: https://datacarpentry.org/lessons/
 [dc-site]: https://datacarpentry.org/
@@ -114,10 +234,11 @@ email][contact].
 [github-flow]: https://guides.github.com/introduction/flow/
 [github-join]: https://github.com/join
 [how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
-[issues]: https://carpentries.org/help-wanted-issues/
+[issues]: https://github.com/epiverse-trace/tutorials/issues
 [lc-issues]: https://github.com/issues?q=user%3ALibraryCarpentry
 [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry
 [swc-lessons]: https://software-carpentry.org/lessons/
 [swc-site]: https://software-carpentry.org/
 [lc-site]: https://librarycarpentry.org/
 [template-doc]: https://carpentries.github.io/workbench/
+[repo-branches]: https://github.com/epiverse-trace/tutorials/branches

LICENSE.md

@@ -4,7 +4,9 @@ title: "Licenses"
 
 ## Instructional Material
 
-All Carpentries (Software Carpentry, Data Carpentry, and Library Carpentry)
+The tutorials in this repository are developed by Epiverse-TRACE, based on the [lesson template from the Carpentries](https://github.com/carpentries/workbench-template-rmd) (template under CC BY license).
+
+All Epiverse-TRACE
 instructional material is made available under the [Creative Commons
 Attribution license][cc-by-human]. The following is a human-readable summary of
 (and not a substitute for) the [full legal text of the CC BY 4.0
@@ -23,8 +25,8 @@ terms.
 Under the following terms:
 
 - **Attribution**---You must give appropriate credit (mentioning that your work
-  is derived from work that is Copyright (c) The Carpentries and, where
-  practical, linking to <https://carpentries.org/>), provide a [link to the
+  is derived from work that is Copyright (c) Epiverse-TRACE, where
+  practical, linking to <https://epiverse-trace.github.io/>), provide a [link to the
   license][cc-by-human], and indicate if changes were made. You may do so in
   any reasonable manner, but not in any way that suggests the licensor endorses
   you or your use.
@@ -45,7 +47,7 @@ Notices:
 ## Software
 
 Except where otherwise noted, the example programs and other software provided
-by The Carpentries are made available under the [OSI][osi]-approved [MIT
+by Epiverse-TRACE are made available under the [OSI][osi]-approved [MIT
 license][mit-license].
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
@@ -66,14 +68,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-## Trademark
-
-"The Carpentries", "Software Carpentry", "Data Carpentry", and "Library
-Carpentry" and their respective logos are registered trademarks of [Community
-Initiatives][ci].
-
 [cc-by-human]: https://creativecommons.org/licenses/by/4.0/
 [cc-by-legal]: https://creativecommons.org/licenses/by/4.0/legalcode
 [mit-license]: https://opensource.org/licenses/mit-license.html
-[ci]: https://communityin.org/
 [osi]: https://opensource.org