Skip to content

Commit

Permalink
Edits to default template files (#2)
Browse files Browse the repository at this point in the history 
* Edited some FIXME issues in config.yaml

* Edits to default reference and setup files

Added RStudio as a setup requirement

* Changed from text lesson to tutorial for consistency

* Minor edit to default instructor notes file

* Update README.md

* Revert "Update README.md"

This reverts commit 2c7028f.

* Change R project name to reflect repo name

* add epiverse-trace CoC to CoC file

* fixes #7

* replace organization names and links

* Fixes #9

* fix #5

* add suggested content in #9

* show visually link when available

* clean setup

---------

Co-authored-by: Andree Valle <[email protected]>
  • Loading branch information
@amanda-minter @avallecam
amanda-minter and avallecam authored Oct 23, 2023
1 parent 4d96dd7 commit b8cad63
Show file tree
Hide file tree
Showing 10 changed files with 197 additions and 145 deletions.
8 changes: 5 additions & 3 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
95 changes: 77 additions & 18 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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 [The Epiverse-TRACE][cp-site] agrees to abide by
our [code of conduct](CODE_OF_CONDUCT.md).

### How to Contribute
Expand All @@ -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].

Expand All @@ -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
Expand All @@ -70,9 +68,70 @@ 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 “development 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:

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.

#### Reviewer:

You can follow this steps:

- Clone the repo or Pull the branch on Rstudio.
- Checkout to the branch to review.
- Use [`renv::restore()`](https://carpentries.github.io/sandpaper/reference/dependency_management.html#details) to align the packages in your cache with the ones in the `renv.lock` file (defined by the Developer).
- 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.
- Make any edit suggestion in the `.Rmd` files inside the `episodes/` folder.

#### Maintainer:

You can follow this references:

- Update steps above from any discussion on 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). Lessons outside of the carpentries need to [set up a Pull Request bot](https://carpentries.github.io/sandpaper-docs/pull-request.html#automated-pull-requests) with the [Carpentries Apprentice bot](https://github.com/carpentries-bot).

### 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
Expand All @@ -95,17 +154,17 @@ final say over what gets merged into the lesson.

### 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-issues]: https://github.com/epiverse-trace/tutorials/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/
Expand All @@ -114,7 +173,7 @@ 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/
Expand Down
52 changes: 52 additions & 0 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
```

# tutorials

<!-- badges: start -->
[![](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Project Status: WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
<!-- badges: end -->

The goal of `tutorials` is to host tutorials for Outbreak analytics with R.

## Usage

Visualize this content as a webpage at <https://epiverse-trace.github.io/tutorials/>

To build the website locally, please refer to [the contributing guidelines](CONTRIBUTING.md).

## Contributing

Contributions are always welcome!

See our [Contributing guide](CONTRIBUTING.md) for ways to get started.

Please adhere to this project's [Code of Conduct](CODE_OF_CONDUCT.md).

<!-- ## Support -->

<!-- Please see our [Getting help guide](/.github/SUPPORT.md) for support. -->

## License

Read the [License](LICENSE.md) of this tutorial.

## Authors

- [@avallecam](https://github.com/avallecam/)
- [@amanda-minter](https://github.com/amanda-minter/)

```{r,eval=FALSE,echo=FALSE}
readCitationFile(file = "inst/CITATION")
```
114 changes: 43 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,43 @@
# The Carpentries Workbench Template R Markdown Lesson

This lesson is a template lesson that uses [The Carpentries Workbench][workbench].

## Create a new repository from this template

To use this template to start a new lesson repository,
make sure you're logged into Github.
Visit https://github.com/carpentries/workbench-template-md/generate
and follow the instructions.
Checking the 'Include all branches' option will save some time waiting for the first website build
when your new repository is initialised.

If you have any questions, contact [@zkamvar](https://github.com/zkamvar)

## Configure a new lesson

Follow the steps below to
complete the initial configuration of a new lesson repository built from this template:

1. **Make sure GitHub Pages is activated:**
navigate to _Settings_,
select _Pages_ from the left sidebar,
and make sure that `gh-pages` is selected as the branch to build from.
If no `gh-pages` branch is available, check _Actions_ to see if the first
website build workflows are still running.
The branch should become available when those have completed.
1. **Adjust the `config.yaml` file:**
this file contains global parameters for your lesson site.
Individual fields within the file are documented with comments (beginning with `#`)
At minimum, you should adjust all the fields marked 'FIXME':
- `title`
- `created`
- `keywords`
- `life_cycle` (the default, _pre-alpha_, is the appropriate for brand new lessons)
- `contact`
1. **Annotate the repository** with site URL and topic tags:
navigate back to the repository landing page and
click on the gear wheel/cog icon (similar to ⚙️)
at the top-right of the _About_ box.
Check the "Use your GitHub Pages website" option,
and [add some keywords and other annotations to describe your lesson](https://cdh.carpentries.org/the-carpentries-incubator.html#topic-tags)
in the _Topics_ field.
At minimum, these should include:
- `lesson`
- the life cycle of the lesson (e.g. `pre-alpha`)
- the human language the lesson is written in (e.g. `deutsch`)
1. **Adjust the name of the `.Rproj` file.**
It is simplest to make this match the name of the repository.
1. **Adjust the
`CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE.md` files**
as appropriate for your project.
- `CODE_OF_CONDUCT.md`:
if you are using this template for a project outside The Carpentries,
you should adjust this file to describe
who should be contacted with Code of Conduct reports,
and how those reports will be handled.
- `CONTRIBUTING.md`:
depending on the current state and maturity of your project,
the contents of the template Contributing Guide may not be appropriate.
You should adjust the file to help guide contributors on how best
to get involved and make an impact on your lesson.
- `LICENSE.md`:
in line with the terms of the CC-BY license,
you should ensure that the copyright information
provided in the license file is accurate for your project.
1. **Update this README with
[relevant information about your lesson](https://carpentries.github.io/lesson-development-training/26-external.html#readme)**
and delete this section.

[workbench]: https://carpentries.github.io/sandpaper-docs/

<!-- README.md is generated from README.Rmd. Please edit that file -->

# tutorials

<!-- badges: start -->

[![](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![Project Status: WIP - Initial development is in progress, but there
has not yet been a stable, usable release suitable for the
public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
<!-- badges: end -->

The goal of `tutorials` is to host tutorials for Outbreak analytics with
R.

## Usage

Visualize this content as a webpage at
<https://epiverse-trace.github.io/tutorials/>

To build the website locally, please refer to [the contributing
guidelines](CONTRIBUTING.md).

## Contributing

Contributions are always welcome!

See our [Contributing guide](CONTRIBUTING.md) for ways to get started.

Please adhere to this project’s [Code of Conduct](CODE_OF_CONDUCT.md).

<!-- ## Support -->
<!-- Please see our [Getting help guide](/.github/SUPPORT.md) for support. -->

## License

Read the [License](LICENSE.md) of this tutorial.

## Authors

- [@avallecam](https://github.com/avallecam/)
- [@amanda-minter](https://github.com/amanda-minter/)
Loading

0 comments on commit b8cad63

Please sign in to comment.