Glossary

Clarification of terms used in the project and its documentation.

admin pages: Pages on the race server that can only be accessed by staff users, and allow access to configuration and student data. Paths in URLs generally start with /admin. Admin-only links tend to be pale yellow buttons, to distinguish from public links.
→ the admin dashboard
administrator: An administrator is a staff user with full access to all the admin capabilities of the race server. Some admin functions also require knowing the authorisation code. There should always be at least one administrator (the username/account is created during the set-up phase).
→ user management
announcement: Announcements are messages that are displayed either at the top of every page on the race server (except the tech notes), or in specific places (such as the login screen).
→ managing announcements
ASBP: The Acme School of Buggy Programming, a fictitious institution and the default value for the "Org" (Organisation) config settings, which you use to customise the buggy server to match your own institution.
→ "Org" config settings
authorisation code, auth code: A code that an administrator needs to present in order to perform some admin functions, including changing config settings, user data, and some other "risky" behaviour. Depending on how big your team is, it's feasible for not all admin users to know the auth code.
→ configuring authorisation
buggy: A racing buggy. In the project, the student develops an app for editing the specification of a buggy, which is expressed as JSON data.
buggy editor: The basic Python Flask application that each student is given at the start of the project, and which they need to develop to add more features and functionality.
→ about the buggy editor
comments: Comments on a user are only visible to staff users (depending on config settings, all staff may be able to edit them, or just administrators).
→ commenting on users
config setting: The config settings control the behaviour and customisation of the race server. You can edit them in the config admin pages (that is, through the web interface), but they can also be set use environment variables if you have access to the server itself. For convenience, config settings are grouped thematically (for example, all the config settings affecting races are in the group "Races").
→ customising (with config settings)
cost: Most components of a racing buggy have a cost. The total cost of a buggy is the sum of the costs of all its components. Cost matters because one of the race rules is that a buggy's total cost must be equal or less than the cost threshold of the race: if it's not, the buggy has a race violation and can't participate in that race.
demo site: We run a demonstration server at https://demo.buggyrace.net so you can see what your might server will look like. Contact us and ask for an admin login to have a poke around backstage.
→ go to the demo site
demo user: This is a special flag we set on admin users on the demo site so they can't accidentally lock other admins (us) out of the demo site. If you spot this at all it will only be on our demo site — you won't see this on your own site because yours isn't a demo!
Docker: Docker is a software tool that wraps applications in "containers" that work in different environments in isolation. The race server is "dockerised" so it can be installed using Docker.
→ Docker website
ext_id: An "external identifier", which is a field you can choose to add to all users. This may be helpful if you need to link students in another system, for example if you're using an online framework like Moodle. The race server doesn't use this — it's just for your information (but might be handy if you need to automate submission of marks or feedback, for example).
→ "Users" config settings
ext_username: An "external username", which is a field you can choose to add to all users. This may be useful if you identify students by their college username, for example (or if your students are running the buggy editor on a remote server via VSCode and they need this to login to that, external, server).
→ "Users" config settings
Flask: The lightweight Python webserver the project uses.
→ Flask docs
Greensock (GSAP): A widely-used JavaScript library for managing animation on web pages, used by the race player to replay the races.
→ GSAP website
hamster: A small rodent (Mesocricetus roadentus) that is used as a form of motive power in some racing buggies.
Heroku: A cloud-based service that hosts websites — see the instructions for installing the race server on Heroku (there is a fee for hosting sites)
→ Heroku website
Jinja templates: The templating system used inside Flask (for example, for specifying HTML pages).
→ Jinja2 docs
mass: Most components of a racing buggy have a mass. The total mass of a buggy may be a factor of its performance during the race. The mass values are available as part of the specs.
Pelican: Pelican is a Python-based static site generator. When you publish the tech notes, the race server uses Pelican behind the scenes to convert the (mostly) markdown source files into pretty HTML pages. The server handles this for you, so you don't need Pelican unless you decide to extract and host the tech notes yourself. (If you're familiar with GitHub Pages: Pelican is effectively a Python-only alternative to Jekyll).
→ Pelican website
petrol: Gasoline. Buggy racing was written in British English, but — because CSS is the relevant context here — the "JSON names" (and hence column names) for buggy data require the US spelling of color. Since the table also includes armour (which isn't a CSS keyword), this is a sneaky but perhaps early lesson in close reading. Ouch!
phase: The tasks students must do are grouped into phases. All the tasks in a phase should be completed before the student can move onto the next phase.
→ tasks and phases
poster: "Poster" is an alternative name for the students' report (it's an anomaly from the RHUL marking scheme that we needed to use — you should just use the word "report").
→ students' posters (i.e., reports)
race event: The details of what happens in a race — running out of fuel, attacking another buggy, moving forward — are recorded as events, which the race player replays. Race events are stored in the race file (not the database).
→ replaying races
race file: Races are created on the race server but are run offline: you download the race file which contains all the data needed to run the race. The results are added to the race file together with the race events. You can upload this race file to add (and publish) the results of the race. The race player can replay a race if it has access to a race file that contains the race's events. The race file is in JSON format.
→ uploading race results
race player: The (JavaScript-powered) web page that replays the events of a race. By default, the race server hosts a race player, but if you make a custom version you can use that instead. The race player takes a race file as its input — it doesn't need access to the race server or the server's database.
→ replaying races
race rules: The rules that define whether or not a buggy is allowed to take part in a given race. One of the rules is that a buggy must have an even number of wheels. The rules are embedded in the specs.
race server: The server running the website that accepts the buggy JSON that students upload from their editors in order to enter races. It's a Flask webserver that you need to set up to run the project.
→ installing and hosting the race server
racetrack: The racetrack is (of course) the nominal setting of a race — but on the server it effectively means a background image (typically a JPG) and an SVG file that describes the path the buggies will follow.
→ managing and customising racetracks
replay: Once a race has been run, replaying it means animating the events of the race in the race player. It's a bit like replaying a video of the race, but instead of video it's a JavaScript-powered reconstruction of the events recorded in the race file.
→ replaying races
report: You can choose to require your students to submit a report as part of their project submission. Each student's report takes the form of a webpage (at /report) within their buggy editor.
→ students' reports
RHUL: Royal Holloway, University of London — where this Buggy Racing project was conceived and originally implemented.
→ RHUL Computer Science
set-up phase: When the race server is first started, you must change or confirm all the config settings. Until you've done this, the server is in the set-up phase and will not let you access any other pages (except the login, in case you interrupt the browser session while you're in this phase).
→ the set-up phase
specs, specifications: The specs define the acceptable values for racing buggies, including the name of each component, its type, the range of acceptable values it can have, a description of its role, and, where applicable, its cost and mass. The specs also include race rules. The specs are available on the webserver both as human-readable web page and as tabulated data, which may (or may not) be useful to students building their buggy editors.
→ specs on the demo site
SQL: SQL (Structured Query Language) is used to store and recover data about each student's buggy in their config settings. There are examples of SQL (or more specifically, Python calling SQL) in the source code your students start with, so they can make progress with the project even if you're not teaching SQL explicitly.
→ SQL
staff user: A staff user on the race server is an administrator or a Teaching Assistant. Staff users can access the admin pages.
→ user management
static content: Static content on the race server refers mainly to pages that need to be published before they can be accessed. There are three such components: the task list, the tech notes, and the buggy editor zipfile (that last one is optional, depending on how you're distributing the buggy editor source code).
There's a page in the tech notes about the more general business of creating and using static content on the web (see it on the demo server).
→ static content (on the race server)
submission, submit: If you're running the project as an assessed piece of work, which may or may not include a report, then you'll probably need a mechanism by which students submit their work. The server doesn't handle submission itself, but you can use some of the "Project" config settings to inform students about how and when to submit their work.
→ how students submit
task: A task is a unit of work for a student to do. Almost every task can be implemented more or less thoroughly (ideally depending on the ability and experience of the student). Tasks are grouped into phases. The phase is indicated by the digit at the start of the task's mnemonic name.
→ tasks and phases
task list: The task list is the page on the race server that contains all of the tasks for students to do. It includes details and hints for each task, as well as buttons that allow students to enter task texts as they attempt them.
→ the task list
task text: A task text is short text a student saves on the race server describing how they approached or completed a task. The student can download their task texts (possibly as rendered markdown inside HTML) to be added to their report before the project is submitted (if your students are required to submit a report).
→ tracking progress (texts help you with this)
Teaching Assistant (TA): A staff user on the race server who has read-access to student data but limited config/admin access. Depending on config settings, TAs may be able to edit staff comments on users, and reset students' passwords for them.
→ user management
tech notes: This race server includes a set of static web pages that provide supporting material about some of the technical aspects of the project — for example, on the demo server see how Flask works as a webserver. The tech notes can't be edited in place, but you can make and host your own copy and link to those instead.
→ tech notes
violation: A racing buggy only qualifies for a race if it satisfies all the race rules. When you run a race, the rules are checked (technically, this could be called "scrutineering") and each rule that fails is a violation. When the race results are published, the violations for each non-runner are shown. This is significant because a key incentive for a student to build a good buggy editor is to detect and prevent violations.
→ running races
VS Code, Visual Studio Code: VS Code is a widely-used editor and interactive development environment by Microsoft. One way of running the buggy racing project is to set up students' code on a departmental server and access it through VS Code and a SSH tunnel. The advantage of using VS Code in this way is ease of deployment, including the Python plugins — it's relatively straightforward to install on Windows, MacOS and Linux — and that all students are (at least to start with) working in the same editor, which means demos and videos are consistent with what they see on their own screens.
→ "Project" config settings (see IS_USING_REMOTE_VS_WORKSPACE)
webpack: A software tool that bundles up assets like JavaScript, style sheets, and graphics for a webserver. The race server uses webpack, which itself depends on node.js.
→ webpack docs
zipfile: On the race server, there's a special case of the buggy editor source code being made available as a zipped archive. This is the (default) way that it's distributed to students, but isn't needed if you're using GitHub. The contents of the zipfile are typically customised before being created, so this is one of the items of static content on the race server that you may need to publish.
→ distributing the code