diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fba2d6..3f05138 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 @@ -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 @@ -26,7 +25,7 @@ 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 ``` @@ -34,7 +33,7 @@ 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 ``` @@ -42,7 +41,7 @@ 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 ``` @@ -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 @@ -69,17 +68,35 @@ 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 @@ -87,24 +104,5 @@ as well as explains a bit more about them and what they are used for. 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. diff --git a/index.qmd b/index.qmd index ad8b07f..013b3a7 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,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