5 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.

5.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.

5.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

5.3 Setting up a GitHub repository

Warning

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 {{ github_repo_spec }} --source=. --public`

We have a custom command line tool that we developed to help manage GitHub repositories for rostools repositories. While it’s useful for us, it isn’t designed or build in a way that makes it easy for others to use.

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 is 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. Ideally the secrets and variables should be set up in the organization settings. 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, as well as a creating a GitHub secret called UPDATE_VERSION_TOKEN and a variable called UPDATE_VERSION_APP_ID that has the App ID.
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.

5.4 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).

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

5.5 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 GitHub workflow, you can have that release automatically create a record on Zenodo, which is a service that allows you to archive workshops and create a DOI for it.

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.

5.6 Setting up GoatCounter

s If you want to use GoatCounter for website visitor tracking, 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.