Setup
All aboard! Setting up ChooChoo
The typical ChooChoo setup should take roughly one hour. The exact time depends on whether you are using an existing ChooChoo project (in which case setup should be quicker) or creating a ChooChoo project from scratch (in which case setup time will partly depend on how many objectives you are specifying). It will also depend on how familiar you are with the underlying tools: Github, yaml and markdown. If you are stuck, please get in contact using the Github discussions board or via email (see here).
graph LR
A[1. Get ChooChoo files] --> B[4. Set objectives];
A --> D[2. Set repository options];
A --> C[3. Specify settings];
D --> E[5. Generate templates];
C --> E;
B --> E;
E --> F[6. Test setup];
F --> G[7. Share documentation];
1. Get ChooChoo files
There are two ways to get the files required to run ChooChoo:
- [Recommended] Copy the choochoo-template repository into a new Github repository.
- Integrate the choochoo-template repository into an existing Github repository.
The second option requires a solid understanding of Github. We primarily recommend copying the choochoo-template into a new repository. For more setup details please select a tab below.
- Visit github.com/lucydot/ChooChoo-template
- Click on the green
Use this template
button towards the top-right hand corner and selectCreate a new repository
- Tick the box
Include all branches
- Specify the owner, repository name and description
- Click on
Create repository
This option requires a good understanding of Github. Please use with caution. We primarily recommend copying the existing choochoo template repository into a new repository.
-
Copy/clone the contents of https://github.com/lucydot/ChooChoo-template/ into the root of your existing repository on the
main
branch.- You do not need the ChooChoo-template
.git
folder - this can be safely ignored/removed. - Merge the contents of
.github/
into any existing folder of the same name.
- You do not need the ChooChoo-template
Whichever option you choose your repository should be public if you have standard (free) Github account and want to publish tutorials, questions and summary plots online. These will be published from a branch called gh-pages
.
You are advised to create one ChooChoo repository for each class group. This will allow you to track the progress of each individual class rather than all classes combined.
2. Update Github labels and settings
Note
The Github web interface does seem to change on a fairly frequent basis. We will try to keep instructions up-to-date, but please do let us know if they need updating. Issues
and Workflows
(under Actions
) both need to be enabled, this is the current default.
Add Issue labels
You need to add Issue labels to the repository. To do this:
- Click on the
Issues
tab - Click on the
Labels
button - Click on the
New label
button - Type
student
intoLabel name
and clickCreate label
. - Type
instructor
intoLabel name
and clickCreate label
. - Type
question proposal
intoLabel name
and clickCreate label
. - Type
accepted question
intoLabel name
and clickCreate label
.
Create gh-pages branch
You may need to create a gh-pages branch, this will be used to publish webpages from. In some cases this may be automatically generated. To create the gh-pages branch:
- Visit your repository landing page (at github.com/organisation_name/repo_name/)
- Click on
main
towards the top left hand corner - In the box with
find or create a branch
typegh-pages
- Click on
Create branch: gh-pages from main
Add repository secret
Commands to choochoo
trigger a Github Action workflow. By default the action responds to issue comments using secrets.CHOO_ACCESS_TOKEN
. You have to options for generating this token: i) generate the personal access token yourself and add this as a repository secret; ii) Contact ChooChoo developers for the access token. The second option has the advantage that each comment posted from a workflow will be authored by "choochoo-bot".
- Generate a personal access token here (also see docs here). The only scope required is
public_repo
. - Add the CHOO_ACCESS_TOKEN as a repository secret (see docs here).
- Contact us through email and we will send a
CHOO_ACCESS_TOKEN
- Go to
Settings
->Collaborators
->Add people
and add usernamechoochoo-bot
as a collaborator. - Add the CHOO_ACCESS_TOKEN as a repository secret (see docs here).
3. Specify ChooChoo settings
All ChooChoo settings are contained within ./instructor/settings.yml
. This is a yaml file. You can edit plain text files (yaml or Markdown) directly in the Github interface on your web browser without downloading anything.
Important
Remember to add your own Github username to the list of admins
.
Key settings (must edit)
project_title
: The project title.
project_repo
: In the format organisation_name/repo_name
.
admins
: A list of Github usernames without the @
sign.
instructors
: A list of Github usernames without the @
sign.
students
: A list of Github usernames without the @
sign.
web_address
: The web address for this ChooChoo project. In most cases this will be https://username.github.io/repo_name
.
User options (may edit)
questions
: If set to true
students can propose their own questions for the question bank.
votes_required
: The number of votes required before an admin is asked to add a question to the question bank.
gh-pages
: If set to true then the question bank, tutorials and summary plot will be published on the gh-pages
branch.
4. Set ChooChoo objectives
The ChooChoo checklist is generated from ./instructor/objectives.yml
.
Note
- All web links must be given using the full web address including
https://
. - You do not need to provide links for all fields. If there are no links you must use empty square brackets
[]
.
Each ChooChoo checklist contains one or more sections. Each section contains:
name
: Section name.
questions
: A list of links to questions associated with this section.
tutorials
: A list of links to tutorials associated with this section.
links
: A list of other links associated with this section.
objectives
: A list of objectives (see below).
Each objective contains:
name
: Objective name/description.
questions
: A list of links to questions associated with this objective.
tutorials
: A list of links to tutorials associated with this objective.
links
: A list of other links associated with this objective.
5. Generate templates
- Visit your choochoo repository (at github.com/organisation_name/repo_name)
- Click on the
Issues
tab towards the top of the page - Click on
New Issue
- Click
Get Started
next toChooChoo instructor thread
- Click
Submit new issue
- In the comment box type
choochoo build checklists
Note
Each choochoo
command takes a couple of minutes to run.
If the choochoo
command is a success you will see a reply in the issue thread.
6. Test setup
- Visit your choochoo repository (at github.com/organisation_name/repo_name)
- Click on the
Issues
tab towards the top of the page - Click on
New Issue
- Click
Get Started
next toChooChoo student thread
- Click on
Preview
to check the formatting looks correct - Click
Submit new issue
to automatically generate a checklist - Read through the checklist and double check formatting, spelling, links etc
If questions
are enabled:
- Repeat for
Question thread
(if questions are enabled)
If gh-pages
is enabled:
- Visit the repository website (most likely organisation_name.github.io/repo_name) to verify that a page exists
7. Share documentation
Important
The objective list should not be adjusted once your class is in progress.
Strange things will happen if student
or question
issues are raised for different objectives -
this includes objective lists that are changed, re-ordered or re-worded.
Although some students will be comfortable using ChooChoo with minimal support or documentation, some may benefit from a walkthrough tutorial. We suggest sharing the link to the student documentation on your course webpage(s) and communication channels. In addition, we encourage you to do a live walkthrough of the steps contained in student setup and student basic usage.