Skip to content

docs: 馃摑 update description of dependencies #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lwjohnst86 merged 2 commits into from
Aug 24, 2026
Merged

docs: 馃摑 update description of dependencies #115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8e2f2d5
docs: 馃摑 add-description-of-dependecies
DanMazJen Aug 10, 2026
caa337c
chore: 鉁忥笍 automatic pre-commit hook fixes
pre-commit-ci[bot] Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 32 additions & 34 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,8 @@
## :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.
find while using template-workshop. You can do this by creating a new
issue on our GitHub repository.

## :pencil2: Adding or modifying content

Expand All @@ -14,7 +13,7 @@ If you would like to contribute content, please check out our
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
To contribute to `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
Expand All @@ -26,23 +25,23 @@ It's easiest to first
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:

``` 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
(`template-workshop/`) and running:

``` bash
```bash
just run-all
```

Expand All @@ -55,11 +54,11 @@ 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/).
[Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/).
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.
revise the pull request title to follow that format. That's because 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

Expand All @@ -69,42 +68,41 @@ 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.
- `.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.
- `_quarto.yml`: Quarto configuration file for the website, including
settings for the website, such as the theme, navigation, and other
options.
- `_metadata.yml`: Quarto metadata file for the website, including
information about the project, such as the titles and GitHub names.
- `.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.
- `.config/`: Contains configuration files for various tools used in the
project, such as:
- `typos.toml`: [typos](https://github.com/crate-ci/typos) spell
checker configuration file.
- `rumdl.toml` and `panache.toml`: [rumdl](https://rumdl.dev) and
[Panache](https://panache.bz) configuration file for formatting
Markdown files in the project.
- `cog.toml`: [Cocogitto](https://docs.cocogitto.io) configuration
file for managing versions.
- `cliff.toml`: [git-cliff](https://git-cliff.org) configuration file
for creating the changelog.
- `.editorconfig`: Editor configuration file for
[EditorConfig](https://editorconfig.org/) to maintain consistent
coding styles across different editors and IDEs.
- `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.
- `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,
[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/)
configuration file for managing versions and changelogs.
87 changes: 43 additions & 44 deletions index.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -40,40 +39,40 @@ 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/) and [panache](https://panache.bz/) 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/).
[Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/)
that are based on messages following [Conventional
Commits](https://decisions.seedcase-project.org/why-conventional-commits/).
- Automatically generating a changelog using
[git-cliff](https://decisions.seedcase-project.org/why-changelog-with-git-cliff/)

## 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

Expand Down
Loading