README.qmd

---
format: gfm
---

# {{< meta titles.full >}}

{{< include /includes/_badges.qmd >}}

## Description

GitHub is increasingly used as a platform for collaborating and sharing
research projects, not only for code but for documents. This workshop
aims to introduce learner to the basics of using GitHub for managing
files and tracking changes to those files (version control). The
workshop is designed for learner who have little to no experience with
Git and GitHub.

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 urls.home >}}).

::: callout-tip
This workshop repository was generated from the
[`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. Challenges 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/`: Contains the files that give an overview to the course,
    such as the syllabus and schedule.
-   `pre-workshop/`: Contains the files necessary for use before the
    workshop, for instance 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 pre-workshop tasks, code of conduct, resources, and instructions
    for teachers.
-   `slides/`: The lecture slides are rendered into HTML slides from
    Markdown.

The website is generated from [Quarto](https://quarto.org/), so it
follows the file and folder structure conventions from that package.

## Support and infrastructure files

-   `.copier-answers.yml`: Contains the answers you gave when copying
    the project from the template. **You should not modify this file
    directly.**
-   `.cz.toml`:
    [Commitizen](https://commitizen-tools.github.io/commitizen/)
    configuration file for managing versions and changelogs.
-   `.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.
-   `.zenodo.json`: Structured citation metadata for your project when
    archived on [Zenodo](https://zenodo.org/). 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/getting-started/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.

## 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://r-cubed.rostools.org/for-teachers.html) 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.

### Contributors

{{< include /includes/_contributors.qmd >}}

## Licensing

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.

To help with general admin tasks of running the workshop, there is the
[samwise](https://github.com/rostools/samwise) R package.

## Changelog

For a list of changes, see our [changelog](CHANGELOG.md) page.

::: content-hidden
### How to cite the material

Please cite the material as:

> TODO: Update when the workshop is published.

Or as BibTeX:

TODO: Update when the workshop is published.
:::