4 Next steps

While most of the post-applying steps are listed in the created TODO.md file within the workshop, this documents some more details for these steps. Use this guide alongside the TODO.md to complete those tasks. For example, one of the first tasks is to start having Git track the workshop with git init. There are two sets of tasks: required and optional.

4.1 Required

These next steps are required in order to actually set up the workshop’s website.

4.1.1 Setting up a GitHub repository

One of the main purposes of this template and using these tools and workflows from it is to make the material public and create a website for the workshop. In order to do that, it needs to go on some type of work

These series of steps are only necessary if you are using this template for a repository that is part of rostools. If you want a quick way of putting your workshop on GitHub, you can use the gh command line tool to upload the workshop to GitHub:

Terminal

gh repo create --source=. --public --push USER/REPO

Tip

If you’re using the template to create a workshop within the rostools GitHub organization, use the instructions below that use a custom command line tool. We built this tool to help us manage our many GitHub repositories across several projects. While it’s useful for us, it isn’t designed or built in a way that makes it easy for others to use (yet).

For setting up a GitHub repository for the created workshop that will be part of rostools, you’ll need to install the Seedcase Project’s (a “sibling” organisation) internal tool spaid and use the following commands to run the next setup steps:

Terminal

spaid_gh_create_repo_from_local -h
spaid_gh_set_repo_settings -h
spaid_gh_ruleset_basic_protect_main -h
spaid_gh_ruleset_require_pr -h

Some configuration may be needed after copying this template to a new repository, including configuration external to the repository. Some GitHub workflows require installing GitHub Apps, for greater security purposes and easier administration when managing multiple repositories. The security section in our Guidebook provides some instructions on how to set up GitHub Apps, secrets, and variables. In the case of rostools, these have already been set up. The specific workflows in this template that require this additional setup are:

The workflow .github/workflows/release.yml requires the auto-release-token GitHub App, which is specific to the Seedcase Project but usable within rostools. This workflow requires that the GitHub secret UPDATE_VERSION_TOKEN and a variable called UPDATE_VERSION_APP_ID are connected to the repository.
The workflow .github/workflows/add-to-project.yml requires the add-to-board-token GitHub App (another Seedcase app), along with the ADD_TO_BOARD_TOKEN secret and the ADD_TO_BOARD_APP_ID variable of the GitHub App’s ID. These will already be set up to work in all public repositories on rostools.

4.2 Connecting to hosting services

If you use this template to make a website hosted on Netlify, you need to connect the GitHub repository to Netlify. The Quarto documentation has an excellent guide on how to do this. It includes configuring Netlify to host the website and adding the NETLIFY_AUTH_TOKEN secret to the GitHub repository (or ideally at the organization level).

Note

Since all rostools workshops use Netlify, any workshops created for rostools already has NETLIFY_AUTH_TOKEN connected to any public repository on rostools.

For hosting on GitHub Pages, it’s a bit easier to set up than Netlify. The Quarto documentation again has a guide on how to do this. Before you can host on GitHub Pages, you need to use Quarto to set things up for you, by running the following command:

Terminal

quarto publish github-pages

4.3 Optional

These optional next steps are very helpful for developing and refining workshops. However, they are a bit more advanced than is required, so only do them if you feel comfortable enough with them.

4.3.1 Setting up pre-commit hooks

Pre-commit hooks are scripts that run when committing changes to a Git repository. They are incredibly useful for enforcing coding standards and catching errors early. The justfile contains a install-precommit recipe that sets up the pre-commit hooks for your workshop. Run it by opening a terminal within the workshop directory and running the following command:

Terminal

just install-precommit

This sets up the pre-commit hooks to run standard checks on your repository whenever you commit files to the history. Using pre-commit hooks as part of your workflow is even better if you connect the continuous integration service to your repository. Go to the pre-commit.ci website and follow the instructions there to connect your repository to the service. This will run the pre-commit hooks on every commit you push to the repository, including pull requests, which will ensure that the code is checked for basic issues. It will also keep the pre-commit hooks updated by creating a pull request whenever newer versions of the hooks are available.

4.3.2 Adding the Quarto theme

Warning

This step is only necessary if you are using this template for a repository that is part of rostools. If you are using this template for a different workshop, you can skip this step. If you have your own Quarto theme that you want to use, you can use this step as a general guide on how to add a Quarto theme to your workshop.

For rostools repositories, we have a custom Quarto extension that has our theme called rostools-theme. The justfile has a recipe called update-quarto-theme that adds this theme to the workshop. Run it by opening a terminal within the workshop directory and running the following command:

Terminal

just update-quarto-theme

This adds the rostools-theme Quarto theme to the website, which provides a consistent look and feel across all rostools websites. It’s called update-quarto-theme here since you can use this command to keep the theme updated.

Then to use the theme, you need to update the _quarto.yml file by adding the following lines to the project and format sections:

project:
  type: rostools-theme

# ...

format: rostools-theme-html

4.3.3 Auto-releasing to Zenodo

Warning

This step is only necessary if you are using this template for a repository that is part of rostools. If you are using this template for a different workshop, you can skip this step. If you want to set up auto-releasing to Zenodo for a different workshop, you can use this section to guide you to setting it up for your workshop.

If you create a release on GitHub, either manually or through a workflow, you can connect Zenodo to create records of any releases. Zenodo is a service that allows you to archive content and create a DOI for it, such as the workshop’s material.

GitHub and Zenodo have an integration that, when set up, will automatically create a Zenodo record from a GitHub release. This is useful if you want to create a DOI for your workshop, which will allow you or others to cite it in their work as well as provide more exposure for your workshop. Connecting GitHub to Zenodo is very easy, check out Zenodo’s guide on it.

4.3.4 Setting up GoatCounter

If you want to use GoatCounter for website visitor tracking (no personal data, so no GDPR issues), you need to create a GoatCounter account and set up a new site for your website. Adding a new site is very easy. Go into the “Settings” after logging into your account. Under “Sites”, click “Add new site” and fill in the form with your website’s unique name. You can use the auto-filled name in the includes/site-counter.html file, which has the format of “orgname-reponame” or modify your own.