Computer Science Field Guide Documentation

Welcome to the documentation for the Computer Science Field Guide project. This project’s documentation expands on the general UCCSER documentation, which contains our contributing guide, installation guides, technical stack explanations, style guides, and much more.

This documentation contains information specific to the Computer Science Field Guide project.

The documentation is split into the following sections:

---

Getting Started Documentation

This documentation contains:

• Our expectations of your contributions to the project

• Steps to install the project on your system for local development

• Explainations on how the project is setup

• Quick Starts on how to write and develop for the project

---

Author Documentation

This documentation is for those who want to help write content for the Computer Science Field Guide project, specifically text content. This is the documentation to read if you want to do any of the following (or similar):

• Add a new chapter or chapter section

• Add a translation

---

Developer Documentation

This documentation is for those who want to contribute to developing the Django system for delivering the Computer Science Field Guide content. This is the documentation to read if you want to do any of the following (or similar):

• Edit HTML templates used to render webpages

• Edit CSS used for styling the website

• Edit the static files (images, CSS, JavaScript, etc) used within the website

• Add an interactive to the website

• Contribute to the test suite for checking database models

• Alter URL routing for views

---

Getting Started

This documentation will help you understand how the project is setup, basic steps on how to use it, and our guidelines for your contributions.

Note

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please read our Code of Conduct before continuing. You can report unacceptable behaviour by emailing us.

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

• Using welcoming and inclusive language

• Being respectful of differing viewpoints and experiences

• Gracefully accepting constructive criticism

• Focusing on what is best for the community

• Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

• The use of sexualized language or imagery and unwelcome sexual attention or advances

• Trolling, insulting/derogatory comments, and personal or political attacks

• Public or private harassment

• Publishing others’ private information, such as a physical or electronic address, without explicit permission

• Other conduct which could reasonably be considered inappropriate in a professional setting

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

Scope

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at csse-education-research@canterbury.ac.nz. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project’s leadership.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 1.4.

Contributing Guide

This page lists a set of guidelines for contributing to the project. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.

Reporting Issues and Making Suggestions

This section guides you through submitting an issue or making a suggestion for the CS Unplugged project. Following these guidelines helps maintainers and the community understand your findings.

Before Submitting an Issue

• Search the issue tracker for the issue/suggestion to see if it has already been logged. If it has, add a comment to the existing issue (even if the issue is closed) instead of opening a new one.

How do I Submit a Good Issue or Suggestion?

Issues are tracked in the GitHub issue tracker (if you’ve never used GitHub issues before, read this 10 minute guide to become a master). When creating an issue, explain the problem and include additional details to help maintainers understand or reproduce the problem:

For Reporting an Issue

• Use a clear and descriptive title for the issue to identify the problem.

• Clearly and concisely describe the issue and provide screenshots if required.

• Link any related existing issues.

If the issues is a code related issue, also include the following:

• Describe the exact steps which reproduce the problem in as many details as possible. For example, how you were generating a resource. When listing steps, don’t just say what you did, explain how you did it.

• Explain which behavior you expected to see instead and why.

• Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior.

• Can you reliably reproduce the issue? If not, provide details about how often the problem happens and under which conditions it normally happens.

• Include screenshots or animated GIFs if it helps explain the issue you encountered.

• What’s the name and version of the OS you’re using?

• What’s the name and version of the browser you’re using?

• If the problem is related to performance, please provide specifications of your computer.

For Making a Suggestion

Explain the suggestion and include additional details to help maintainers understand the changes:

• Use a clear and descriptive title for the issue to identify the suggestion.

• Clearly and concisely describe the suggestion and provide screenshots if required.

• Explain why this suggestion would be useful to most CS Unplugged users and isn’t something that should be a implemented as a community variant of the project.

• Link any related existing suggestions.

Note

Internal Staff Only: Assigning Issues

Our policy is to only assign a person to an issue when they are actively working on the issue. Please don’t assign yourself when you plan to do the task (for example: in the next few days), assign yourself when you begin work. This allows other team members to clearly see which tasks are available to be worked on.

Your First Code Contribution (pull request)

Unsure where to begin contributing to CS Unplugged? You can start by looking through the issue tracker.

Pull Requests

• Include a detailed explaination of the proposed change, including screenshots and animated GIFs in your pull request whenever possible.

• Read and apply the style guides listed below.

• Your pull request should be on a new branch from our develop branch, that is being requested to merge back into develop. The naming conventions of branches should be descriptive of the new addition/modification. Ideally they would specify their namespace as well, for example:

  • resource/puzzle-town

  • topic/algorithms

  • issue/234

• Link to any relevant existing issues/suggestions.

• Add necessary documentation (if appropriate).

We aim to keep the CS Unplugged project as robust as possible, so please do your best to ensure your changes won’t break anything!

Style and Etiquette Guides

Git

• Commits should be as descriptive as possible. Other developers (and even future you) will thank you for your forethought and verbosity for well documented commits. Generally:

  • Limit the first line to 72 characters or less

  • Reference issues and pull requests liberally

• We use Vincent Driessen’s Git Branching Model for managing development. Please read this document to understand our branching methods, and how to perform clear branches and merges.

  Specifically for our respository:

  • We create a new branch for each task of work, no matter how small it is.

  • We create the branch off the develop branch.

  • In general, the new branch should begin with issue/ followed by the issue number.

  • When a branch is completed, a pull request is created on GitHub for review.

  • Branches are merged back into develop.

GitHub

Note

Internal Staff Only

• Mention a user (using the @ symbol) when an issue is relevant to them.

• Only assign yourself to an issue, when you are actively working on it.

• The technical team may tag an author to review specific pull requests, and as a reviewer you can either approve, request changes, or just leave comments.

• A pull request requires one review approval to be merged.

• If multiple people are tagged as reviewers, we only need one review (unless otherwise specified). For example: For content changes, we ask that at least one member from each of the content and technical teams reviews the pull request.

• The creator of the pull request should assign all those suitable for review.

• The creator of the pull request is the only person who should merge the pull request. If you approve a pull request and it shows the big green button, please resist clicking it!

Project Structure

• Directories should be all lowercase with dashes for spaces.

• Directories and files should use full words when named, however JavaScript, CSS, and image directories can be named js/, css/, and img/ respectively.

Text (Markdown)

• Each sentence should be started on a newline (this greatly improves readability when comparing two states of a document).

Programming

Quote from Google style guides:

Be consistent.

If you’re editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you’re saying rather than on how you’re saying it. We present global style rules here so people know the vocabulary, but local style is also important. If code you add to a file looks drastically different from the existing code around it, it throws readers out of their rhythm when they go to read it. Avoid this.

We aim to abide by the following style guides:

• Python - We follow PEP8 except for one change of line length. Django recommends allowing 119 characters, so we use this as our line length limit. This style is enforced by the flake8 style checker.

• HTML - We follow the open source HTML style guide by @mdo.

• CSS - We follow the open source CSS style guide by @mdo.

• JavaScript - We follow the Google JavaScript style guide.

Licencing

Any third-party libraries or packages used within this project should have their listed within the LICENCE-THIRD-PARTY file, with a full copy of the licence available within the third-party-licences directory.

Final Comments

After reading the sections above, you should be able to answer the following questions:

• When do I create a issue and how do I describe it?

• When and how do I create a new Git branch to work on?

• Internal staff only: When do I assign myself to an issue?

Installation Guide

This page will set your machine up for working on the CS Field Guide project. You should only need to do these installation steps once (unless the required steps for setup change).

Requirements

• At least 5 GB of hard drive space.

• An internet connection to download 1 to 2 GB of data.

Recommended Reading

If you aren’t familiar with the following systems, we recommend reading tutorials first on how to use them:

• Entering terminal commands for your operating system

• Git (here are two Git tutorials: one two)

Step 1: Install Git

Install the version control software Git onto your computer.

Note

If you are new to Git and not comfortable with using the terminal, you may like to use a free program like SourceTree to use Git.

Step 3: Create GitHub Account

If you don’t already have an account on GitHub, create a free account on the GitHub website. This account will be tied to any changes you submit to the project.

Step 4: Set Git Account Values

When you make a commit in Git (the term for changes to the project), the commit is tied to a name and email address. We need to set name and email address within the Git system installed on the machine.

• Setting your username in Git

• Setting your email in Git

You can also keep your email address private on GitHub if needed.

Note

If your GitHub account is secured with two-factor authentication (2FA) this is a perfect time to setup SSH keys.

Step 5: Download the CS Field Guide Repository

Firstly create the directory you wish to hold the CS Field Guide repository directory in if you wish to store the data in a specific location. Once you have decided upon the location, clone (the Git term for download) the project onto your computer.

If you are using terminal commands to use Git, type the following command in terminal (you don’t need to enter the $ character, this shows the start of your terminal prompt):

$ git clone https://github.com/uccser/cs-field-guide.git

Note

If you connect to GitHub through SSH, then type:

$ git clone git@github.com:uccser/cs-field-guide.git

This may be necessary if you use two-factor authentication to login to GitHub. See the note in Step 4 for help with setting up SSH keys with this.

Once Git has cloned the directory, checkout the repository to the development branch develop.

Step 6: Install Docker

We use a system called Docker to run the CS Field Guide system, both on local machine for development, and also when deployed to production.

Linux

While it is possible to install Docker Desktop on Linux, we recommend installing Docker Engine and Docker Compose individually.

With these installed, for our dev script to work, you need to be able to manage docker as a non root user. See these instructions on how to do this.

Once you have installed the software, run the following commands in a terminal to check Docker is working as intended (you don’t need to enter the $ character, this shows the start of your terminal prompt).

$ docker version
$ docker compose version
$ docker run hello-world

Windows

If you are using Windows, we highly recommend using Docker Desktop in combination with the Windows Subsystem for Linux. See here for installation instructions.

Mac

If you are using macOS, Docker Desktop would likely be your best bet, however we haven’t tested the installation on macOS yet.

Step 7: Install Text Editor/IDE (optional)

This is a good time to install your preferred IDE or text editor, if you don’t have one already. Some free options we love:

• Visual Studio Code

• Sublime Text

Step 8: Check Project Setup Works

To check the project works, open a terminal in the project root directory, which is the cs-field_guide/ directory (should contain a file called dev).

Type the following commands into the terminal (we will cover these commands in more detail on the next page):

$ ./dev start
$ ./dev update

If this is the first time you’re running this script, it will need to build system images. This can take some time, roughly 15 to 30 minutes, depending on your computer and internet speed (we recommend grabbing a cup of tea and watching an episode of Brooklyn Nine-Nine on Netflix).

After the helper script builds the system images, it will automatically start the system, and will let you know when the system is ready. You should then be able to open your preferred web browser to the URL cs-field-guide.localhost and see the CS Field Guide homepage.

If you are working on documentation, navigate to docs.cs-field-guide.localhost. This is a live server, so any changes you make to the documentation should be visible on the webpage within a couple seconds of saving the file.

Congratulations if you made it this far and everything is working, you’re all set to contribute to the CS Field Guide project.

Project Structure

This page covers the structure of the CS Field Guide project. The following diagram will be helpful when reading the following sections:

├── csfieldguide/
│   ├── appendices/
│   ├── build/
│   ├── chapters/
│   ├── config/
│   ├── curriculum_guides/
│   ├── general/
│   ├── interactives/
│   ├── locale/
│   ├── search/
│   ├── static/
│   ├── staticfiles/
│   ├── templates/
│   ├── tests/
│   ├── third-party-licences/
│   ├── utils/
│   ├── gulpfile.js
│   ├── make-interactive-thumbnails.js
│   ├── manage.py
│   └── package.json
├── docs/
├── requirements/
├── subtitles/
├── third-party-licences/
├── LICENCE
├── LICENCE-CONTENT
├── LICENCE-THIRD-PARTY
└── README.md

Repository Directory

The repository directory (or root directory) contains the following:

• csfieldguide/

  • This directory contains the Django web system for the CS Field Guide website. This includes all raw text content, images, resources, etc.

• docs/

  • This directory contains the documentation for the repository (which includes the file you are reading now).

• subtitles/

  • This directory contains subtitle files for CS Field Guide videos.

• README.md

  • This file contains an introduction and important information for the repository.

• LICENCE.md

  • This file details the licences the repository uses.

• Plus other files used for installation and repository configuration.

csfieldguide Directory

The csfieldguide/ directory holds the Django web system and is split across the following directories:

• config/

  • This directory holds the settings used by the Django system. It’s unlikely you’ll edit the contents of this directory unless you are changing the Django configuration (for example: adding a new application).

• tests/

  • This directory holds all the tests for the project.

• utils/

  • Utility functions used throughout the application. One example would be custom converter templates for Verto.

Django contains ‘applications’ which are Python packages that provide some set of features. Each large part/chunk of the CS Unplugged is a separate application. The project currently contains the following applications:

• general/

  • This application displays webpages for generic pages on the website. For example: homepage, about page, contact page, etc.

• chapters/

  • The core CS Field Guide content is split across chapters, with each topic containing any number of sections. THis applications stores and displays the chapters content.

• curriculum_guides/

  • This application displays a collection of curriculum guides to help teachers use CS Field Guide to help teach their own curriculum.

• interactives/

  • This application contains all of the interactive content used throughout CS Field Guide.

• search/

  • This application contains all the logic and ui to manage searching the entire website.

See the Adding a Chapter quick start for an example of dealing with an application.

The following directories are also required by the Django system:

• static/

  • This directory contains non-user-generated media assets (for example: images, JavaScript, CSS/SCSS, etc).

• staticfiles/

  • This is where static files are served to the different applications inside the project.

• templates/

  • This directory contains all the HTML templates for the Django system.

• locale/

  • This directory contains translations required for the Django system. Translations for topics/ are stored within the topics/content/.

The following directories are used when the server is running (for example: a script compiles the SCSS to CSS and saves it to the build/ directory for serving on a webpage). You should never save anything in these directories, as the contents are often overwritten and cleared.

• build/

  • Contains the generated output of the front-end script (for example: compiled and minified CSS and JavaScript, compressed images, etc).

• temp/

  • Contains temporary files used in creating generated files for build directory.

The csfieldguide/ directory also contains the following files:

• manage.py

  • A file created by Django used to manage the Django web system. Don’t modify the contents of this file.

Helper Commands for Developing

Note

We assume by this point you have installed the project, checked the setup is working (see Step 8: Check Project Setup Works), and also have a basic understanding of the project structure.

The CS Field GUide project uses many systems (Django, Docker, Gulp, etc) to run, so we have written a script for running groups of commands for running the system while developing.

The script is called dev and can be found in the cs-field-guide folder of the repository. To run this script, open a terminal window in the directory and enter the following command (you don’t need to enter the $ character, this shows the start of your terminal prompt):

$ ./dev [COMMAND]

Where [COMMAND] is a word from the list below:

• build

• collect_static

• compilemessages

• end

• exec

• help

• logs

• make_interactive_thumbnails

• makemessages

• makemigrations

• migrate

• reboot_django

• rebuild_index

• restart

• start

• static

• style

• test_backwards

• test_coverage

• test_specific

• test_suite

• update

• update_data

• update_static

All users of the project (content and technical developers) should become familiar with the following commands:

• start

• end

• build

• update

---

build

Running ./dev build will build or rebuild the Docker images that are required for the CS Unplugged system.

---

collect_static

Running ./dev collect_static runs the Django collectstatic command to collect static files. It will copy files under the static/ folder into the staticfiles/ folder.

---

compilemessages

Running ./dev compilemessages runs the Django compilemessages command. This runs over .po files and creates .mo files which are optimised for use by gettext. You will need to run this command after each time you create your message file or each time you make changes to it.

---

end

Running ./dev end will stop any containers which are currently running, this usually takes 10 to 20 seconds.

---

exec

Running ./dev exec allows you to run a command inside a container. This is commonly used to run a bash shell, allowing you to inspect what is going on inside the container.

As an example, ./dev exec django bash would be the equivalent to entering docker compose run django bash

---

help

Running ./dev help displays brief help text for the script. More details for each command can be found on this page.

---

logs

Running ./dev logs will display the logs for the running systems. The output is for all logs until the time the command was run, therefore successive calls may display new logs.

To follow logs as they output, enter docker compose logs --follow.

---

make_interactive_thumbnails

Running ./dev make_interactive_thumbnails generates the thumbnails for the interactives.

---

makemessages

Running ./dev makemessages runs the Djanog makemessages command. This will create message files where each message file represents a single language. Message files contain all available translation strings and how they should be represented in the given language.

---

makemigrations

Running ./dev makemigrations runs the Django makemigrations command to create migration files.

---

migrate

Running ./dev migrate runs the Django migrate command to apply migration files.

---

reboot_django

Running ./dev reboot_django will rebuild the Django Docker container.

---

rebuild_index

Running ./dev rebuild_index will rebuild the search indexes.

---

restart

Running ./dev restart is a shortcut for running:

• ./dev end

• ./dev start

More details for each command can be found on this page.

---

start

Running ./dev start starts the development environment. It performs the following tasks:

• Build system Docker images if required (see below)

• Start the Django website system

• Start the Nginx server to display the website and static files

• Start the database server

When you run this command for the first time on a computer it will also run ./dev build to build the system Docker images. This can take some time, roughly 15 to 30 minutes, depending on your computer and internet speed. Images are only required to be built once, unless the image specifications change (you can rebuild the images with ./dev build). Once the images are built, the script will run these images in containers.

Once the development environment is operational, run the ./dev update command to load the CS Unplugged content.

---

static

Running ./dev static runs the commands for generating the static files for the website.

If changes are made to the static files (for example, a new image is added) when the system is running, this command needs to be entered to view the new files on the website.

style

Running ./dev style will run the flake8 and pydocstyle commands to check the style of the project. If the output is 0 for a check, then there are zero errors.

---

test_backwards

Running ./dev test_backwards will run the test suite in reverse. This is useful to check if any tests are influencing the result of each other. If this command if run on Travis CI, it will only run for a pull request.

---

test_coverage

Running ./dev test_coverage will display a table detailing test code coverage, from the report generated by ./dev test.

---

test_specific

Running ./dev test_specific [MODULE_PATH] will run a specific test module. For example, running ./dev test_specific tests.resources.views.test_index_view will only run the tests for checking the index view of the resources application.

---

test_suite

Running ./dev test_suite will run the test suite, and create a report detailing test code coverage. The code coverage report can be displayed by running ./dev test_coverage.

---

update

Running ./dev update performs the following tasks:

• Update the database with the required structure (known as the schema)

• Load the CS Unplugged content into the database

• Create the required static files

Once the script has performed all these tasks, the script will let you know the website is ready. Open your preferred web browser to the URL cs-unplugged.localhost to view the website.

In more detail, ./dev update runs the Django makemigratations and migrate commands for updating the database schema, and then runs the custom updatedata command to load the topics content into the database. It also runs the static command to generate static files.

If changes are made to the topics content when the system is running, this command needs to be run to view the new changes on the website.

---

update_data

Running ./dev update_data runs the custom update_data command to load the topics content into the database.

---

update_static

Running ./dev update_static generates and collects static files into the staticfiles/ folder. This command is equivalent to running static and then collect_static.

---

You now know the basic commands for using the CS Field Guide system. You are now ready to tackle the documentation for the area you wish to contribute on. Head back to the documentation homepage and choose the documentation related to the task you wish to contribute to.

Author Documentation

The following pages are for those wanting to write or edit Computer Science Field Guide content.

Quick Start - Adding a Chapter

Prerequisites

1. The development server is running (see Step 8: Check Project Setup Works).

2. (optional) A basic understanding of Markdown.

A small note on structure

CSFG content is described using a combination of YAML (see here for a quick run down), for the structure, and an extension of Markdown that we have designed called Verto (see here), used for the actual content that is displayed to the user.

Most content in CSFG, including Chapters and Curriculum Guides, use a very similar folder structure. This means that once you’ve learnt how to create a Chapter, it should be relatively simple to look at adding other content that uses the same structure.

Creating a new chapter

Chapter structure

Navigate to ./csfieldguide/chapters/content. This is where the content for all of the chapters are stored. We can see a few subdirectories. Most of thes are for languages, these contain localised Verto files of the different chapters, broken up by section. The last folder is the structure folder. This is used to describe how the chapters and sections are laid out and ordered.

Here is a diagram of the directory structure at the end of this quick start:

├── chapters/
│   ├── content/
│   │   ├── en/
│   │   │   └── new-chapter/
│   │   │      ├── sections/
│   │   │      │   ├── first-section.md
│   │   │      │   └── another-section.md
│   │   │      └── new-chapter.md
│   │   └── structure/
│   │      ├── new-chapter/
│   │      │   ├── sections/
│   │      │   │   └── sections.yaml
│   │      │   └── new-chapter.yaml
│   │      └── structure.yaml

We will start by creating a chapter called “New Chapter”.

Configuration

1. Under the structure subdirectory, create a new folder with the name new-chapter. This name is referred to as the chapter’s slug. It must be lowercase with hyphens separating words.

2. Inside this folder we can create a chapter configuration file called new-chapter.yaml. This contains some basic information about the chapter. For now, just paste this information into it:

   icon: svg/csfg-icon.svg
   sections: sections/sections.yaml
   

   See the Chapter Configuration File documentation for more info.

3. Staying inside the new-chapter folder, create another folder called sections and add a file inside that is called sections.yaml with this content:

   first-section:
       section-number: 1
   
   another-section:
       section-number: 2
   

   This is called the Chapter Sections Configuration File, and it describes what order the different sections based off of their slugs.

4. Finally, we need to add the chapter to the list of chapters in content/structure/structure.yaml. This is the Application Structure Configuration File. Just below the last chapter definition, add this code with the value in chapter-number replaced with the last chapter-number in the file plus 1. As of writing this, the last chapter number is 18, so I put 19 (Make sure the indentation is the same as the previous lines, YAML is very specific about indentation):

   new-chapter:
       chapter-number: 19
   

Writing the Markdown content

Okay, now that we’re done with the boring configuration, lets get on to writing some content! You can find a reference of all available Markdown and Verto formatting in our writing guide, but a lot of the useful tags also have examples below.

1. First we need a directory for the content to go in. Under content/en create a folder called new-chapter.

2. Let’s start with the introduction page. Under this new folder, create a new file called new-chapter.md and add this text to it:

   # New Chapter (this text becomes the title of the chapter)
   
   This is the opening page of the chapter.
   The Heading 1 (#) becomes the title at the top of this page, and there should be an
   "Introduction" header just underneath it, when it is rendered.
   Multiple sets of whitespace (spaces, tabs, or new lines) are typically shrunken
   down to a single space, making it easy to nicely format the code without changing
   the formatting of the rendered page.
   
   To put a new line in the rendered page, put two new lines in the page.
   So, this should all be a seperate paragraph from the above text.
   You can do **bold**, *italic*, [links](https://csfieldguide.org.nz) and much more.
   
   ### Heading 3
   You can have up to 6 headings by using different numbers of #'s.
   {comment This is a comment, and it won't be visible in the rendered page}
   

3. For the sections, create a new subdirectory of new-chapter and call it sections. For every slug that you defined in step 3 of Configuration, you want to create a file called <slug>.md (replace <slug> with the name of the slug). Here’s some example verto for the two sections, but feel free to come up with your own as well 🙂:

   first-section.md:

   # This becomes the title of this section
   
   Just like for the chapter, the Heading 1 at the top of the file becomes the title
   on the rendered page.
   
   ## Some cool things you can do
   
   {blockquote}
   
   Blockquotes are cool!
   Also for any jargon such as the word {glossary-link term="lossless"}lossless{glossary-link end},
   you can link to the glossary (assuming there is a defintion for the term.
   
   {blockquote end}
   
   {image file-path="img/chapters/jflap-create-state.png" alt="Building an FSA – example" caption="true"}
   
   This is the caption text.
   
   {image end}
   
   ### Video
   
   {video url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
   

   another-section.md:

   # The other section
   
   ## Panels!!!!
   
   {panel type="curiosity"}
   
   # Panels need a title
   
   How curious
   
   {panel end}https://cs-field-guide.readthedocs.io/en/latest/author/writing_guide.html
   
   {panel type="challenge"}
   
   # There are many different types of panels
   
   {blockquote}
   
   You can have other verto features inside panels too!!
   
   {blockquote end}
   
   {panel end}
   
   Below is a teacher panel, if you don't see it, change to teacher mode:
   
   {panel type="teacher"}
   
   # Hidden for everyone but teachers :)
   
   This is hidden unless you are in teacher mode
   
   {panel end}
   
   ## And lastly... interactives
   This is an in-page interactive:
   
   {interactive slug="binary-cards" type="in-page"}
   
   And this is a link to a whole page interactive:
   
   {interactive slug="binary-cards" type="whole-page" parameters="digits=5&start=BBBBB" text="true"}
   
   Binary Cards Interactive
   
   {interactive end}
   

Updating the database

Lastly, we need to update the database. Run ./dev update_data, and you should be able to see your new chapter when you refresh the page!

Writing Guide

The Computer Science Field Guide is developed in English and then translated into other languages. You can find more information about this on the Translations page.

The majority of our text content is written in Markdown, and we also developed a program called Verto to allow you to include HTML elements like images and videos with simple text tags.

For example, the following text:

{panel type="teacher-note"}

# This section contains extension material

This section is an extension aimed at keen students.
Primary school kids have been able to understand many of these ideas, although it really depends on how engaged the students are with the material.

{panel end}

will display as the following on the website:

Note

If you already know Markdown syntax, please remember the following project preferences (for consistency and readability):

• Use asterisks (*) for emphasis, instead of underscores.

• Use hyphens (-) for unordered lists.

• No HTML within text files, we use Verto text tags to add iframes, images, videos, etc.

Below is a basic guide to syntax for Markdown and Verto text tags. When viewing Verto documentation for a tag, the top of the page will detail how to use the tag in a basic example. Some text tags also have required and/or optional tag parameters for further configuration.

---

Blockquotes

> Blockquotes are very handy to emulate reply or output text.
> This line is part of the same quote.

Quote break.

> Oh, you can *put* **Markdown** into a blockquote.

Blockquotes are very handy to emulate reply or output text. This line is part of the same quote.

Quote break.

Oh, you can put Markdown into a blockquote.

---

Boxed Text (Verto feature)

Click here to read the documentation on how to box text.

---

Code

You are able to include code snippets, either in a line of text or as a new block.

To include inline code, add a backtick to either side of the code. For example: `print(“Hi”)` will display as print("Hi"). You cannot set the language syntax highlighting for inline code.

To create a code block, use a line of three backticks before and after the code. You also can add syntax highlighting by specifying the language after the first set of backticks (list of language codes).

```python3
def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far
```

def find_high_score(scores):
    if len(scores) == 0:
        print("No high score, table is empty")
        return -1
    else:
        highest_so_far = scores[0]
        for score in scores[1:]:
            if score > highest_so_far:
                highest_so_far = score
        return highest_so_far

---

Comment (Verto feature)

Click here to read the documentation on how to add a comment.

---

Conditional (Verto feature)

Click here to read the documentation on how to define a conditional.

---

Embedded iframe (Verto feature)

Click here to read the documentation on how to embed with an iframe.

---

Emphasis

Emphasis, aka italics, with *asterisks*.

Strong emphasis, aka bold, with **asterisks**.

Emphasis, aka italics, with asterisks.

Strong emphasis, aka bold, with asterisks.

Note

We do not use underscores for emphasis to maintain consistency and readability.

---

Glossary Link (Verto feature)

Click here to read the documentation on how to define a glossary link.

---

Heading (Verto feature)

Click here to read the documentation on how to create a heading.

---

Image (Verto feature)

Click here to read the documentation on how to include an image.

---

Interactive (Verto feature)

Click here to read the documentation on how to include an interactive.

---

Line Breaks

Here are some things to try out:

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a **separate paragraph**.

This line is also a separate paragraph.
However, *this* line is only separated by a single newline in the markdown file.
These are new sentences that will appear **on the same line** as each previous one.

When writing markdown, new sentences should be started on a new line for clarity.
An exception is for really small sentences like this:
Is it one? two? three?

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph. However, this line is only separated by a single newline in the markdown file. These are new sentences that will appear on the same line as each previous one.

When writing markdown, new sentences should be started on a new line for clarity. An exception is for really small sentences like this: Is it one? two? three?

---

Links

There are several links that may be used:

The general syntax for links is [link text](link url) where link text is the text to be displayed in the document, and link url is the destination of the link.

Escaping closing brackets within link URLs: A closing bracket can be escaped by prefixing it with a backslash \).

Internal links

These are links to pages within the Computer Science Field Guide website. These links will not work when viewed in a Markdown renderer, however these will function properly when converted to HTML and viewed on the website.

Link to Page Within Website (relative link - Verto feature)

You can refer to a chapter page with the following syntax:

[link text]('chapters:chapter' '<chapter-key>')

As an example, the following would link to the complexity and tractability chapter:

[complexity and tractability]('chapters:chapter' 'complexity-and-tractability')

You can link to a chapter section with similar syntax:

[link text]('chapters:chapter-section' '<chapter-key>' '<chapter-section-key>')

Links to an interactive follow the same syntax as a chapter link, except ‘chapter’ is replaced with ‘interactive’.

[link text]('interactives:interactive' '<interactive-key>')

To reference an interactive with URL parameters the syntax is:

[link text]('interactives:interactive' '<interactive-key>'?<url-parameters>)

Examples:

Check out the chapter on [algorithms]('chapters:chapter' 'algorithms').
Check out [interface usability]('chapters:chapter-section' 'human-computer-interaction' 'interface-usability').
[Regular Expression Searcher]('interactives:interactive' 'regular-expression-search')

Slugs are defined in configuration files.

Some pages will not require slugs, such as appendix pages or the homepage.

[link text]('appendices:<url-pattern-name>')

Some examples:

Check out the [about page]('appendices:about').
[Homepage]('general:index')

Click here to read the documentation on how to create a relative link.

Link to a Page Outside of Website (external link)

These are links to websites that are not a part of the Computer Science Field Guide project. The URL should include the https:// or http:// as required.

Check out [Google's website](https://www.google.com).

Create a Link on an Image (Verto feature)

Images should now be linked using the caption-link and source tag parameters for including an image. See the Verto documentation on the image processor for more information and examples.

Create a Link on a Button (Verto feature)

Click here to read the documentation on how to add a button link.

---

Lists

Lists can be created by starting each line with a - for unordered lists or 1. for ordered lists. The list needs to be followed by a blank line, however it doesn’t require a blank line before unless the preceding text is a heading (a blank line is then required). If you are having issues with a list not rendering correctly, try adding a blank line before the list if there is none, otherwise submit a bug report if you are still having rendering issues.

Unordered list:
- Item 1
- Item 2
- Item 3

Ordered list:
1. Item 1
2. Item 2
3. Item 3

Unordered list:

• Item 1

• Item 2

• Item 3

Ordered list:

1. Item 1

2. Item 2

3. Item 3

Nested lists can be created by indenting each level by 4 spaces.

1. Item 1
  1. A corollary to the above item, indented by 4 spaces.
  2. Yet another point to consider.
2. Item 2
  * A corollary that does not need to be ordered.
    * This is indented eight spaces, because it's four for each level.
    * You might want to consider making a new list by now.
3. Item 3

1. Item 1

1. A corollary to the above item, indented by 4 spaces.

2. Yet another point to consider.

2. Item 2

• A corollary that does not need to be ordered.

  • This is indented eight spaces, because it’s four for each level.

  • You might want to consider making a new list by now.

3. Item 3

---

Math

To include math (either inline or as a block) use the following syntax while using LaTeX syntax.

This is inline math: \( 2 + 2 = 4 \)

This is block math:

\[ \begin{bmatrix} s & 0 \\ 0 & s \\ \end{bmatrix} \]

Math equations are rendered in MathJax using the LaTeX syntax.

---

Panel (Verto feature)

Click here to read the documentation on how to create a panel.

Supported panel types

These are the panel types that have built in styling for CSFG. Other panel types can be used, but they will not have any special styling. Have a play around with them to see how they look!

• additional-information

• caution

• curiosity

• challenge

• exercise

• jargon-buster

• project

• spoiler

• teacher-note

  • NOTE: Teacher Notes will only be visible if Teacher Mode is enabled

---

Scratch (Verto feature)

Click here to read the documentation on how to include an image of Scratch block.

---

Table of Contents (Verto feature)

Click here to read the documentation on how to include a table of contents.

---

Tables

Tables can be created using the following syntax:

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

The outer pipes (|) are optional, and you don’t need to make the raw Markdown line up prettily, but there must be at least 3 dashes separating each header cell. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Markdown	Less	Pretty
Still	renders	nicely
1	2	3

---

Video (Verto feature)

Click here to read the documentation on how to include a video.

---

Writing structure

Chapters always contain the following:

• An introduction page, which introduces the reader to the chapter.

• Several chapter sections, which each cover a key sub topic of the main chapter.

• A The whole story! page, which should mention some other related concepts not covered by the chapter.

• A Further reading page, which contains links and/or book references where students can investigate the topic further.

---

Understanding Configuration Files

There is a lot of content within the Computer Science Field Guide project. We split this content across many files and configuration files are the things that bring everything together. These files are used for configuring the content data when stored in the system database, so it’s important to understand how to read and write these configuration files for working on this project.

Here is an example configuration file used to define the order of sections in a chapter in the Computer Science Field Guide project:

searching:
  section-number: 1

sorting:
  section-number: 2

what-makes-an-algorithm:
  section-number: 3

the-whole-story:
  section-number: 4

further-reading:
  section-number: 5

This page aims to give a brief tutorial on YAML files, so you can modify configuration files within this project.

YAML files are mostly made up of key/value pairs, often called a dictionary within programming languages. The first key/value pair in this configuration file is explained below:

• The key searching stores a dictionary of information about that chapter section. In this case, only information about the section number is stored.

• Inside this dictionary, the key section-number stores an integer indicating the number order for this section. For example searching will be the first section, sorting the second and so on.

The majority of configuration files within this project only use dictionaries and lists to store their data. Here are some other useful tips:

# You can include comments in YAML by starting with a # character

# This stores the integer 7 in the key 'number'
number: 7

# This is an ordered list of dictionaries within the key 'difficulties'
difficulties:
  - level: 1
    name: Beginner
  - level: 2
    name: Growing Experience
  - level: 3
    name: Ready to Expand

You may find that there is more than one configuration file that you need to modify/create. This is because it is difficult to read files using deep nesting (indentation), so we have split configuration data across multiple files to avoid this issue.

If you want to learn more about YAML, there are plenty of great tutorials available on the internet.

Chapters

The chapters application is the main focus of the Computer Science Field Guide website, as it contains the majority of educational material for the project.

Chapters Overview

The application is made up of chapters and each chapter is broken down into sections.

Chapters Content Directory

The content directory for the chapters application contains

• a directory for each language in which content exists, named using the Django locale code. This directory contains content Markdown files.

• a special structure directory which contains all configuration YAML files

Content Files

There are 2 different types of files used for adding content to the Computer Science Field Guide:

• Content Markdown files

• YAML configuration files

All files live inside the chapters/content directory. Content Markdown files are unique for each translation language, and are stored in a directory tree specific to that language. This directory is named using the languages Django locale code (for example: en or de). Configuration files are shared amongst all languages, because the content structure is the same for all languages. These files live under a special structure directory.

As a simple rule, structure files situated inside the structure directory contain no text a website user will see. Any user-facing text lives in a Markdown file inside the locale specific directories.

Configuration Files

This section details configuration files within the content/structure directory. These files are in YAML format. If you are not familiar with YAML, see Understanding Configuration Files.

The diagram below shows an example of YAML file locations for the content/structure/ language directory, where:

• Blue is directories.

• Red is YAML configuration files.

├── algorithms/
│   ├── sections/
│   │   └── sections.yaml
│   └── algorithms.yaml
├── artificial-intelligence/
│   ├── sections/
│   │   └── sections.yaml
│   └── artificial-intelligence.yaml
└── structure.yaml

In the following sections, each configuration file is explained in more detail.

Note

• Some of the slugs have angle brackets around them, <like so>. This means that they are variables and you can call them whatever you like in your configuration file (without the angle brackets). Key names should be consistent, i.e every instance of <chapter-slug> should be replaced with the exact same slug.

Application Structure Configuration File

• File Name: structure.yaml

• Location: chapters/content/structure/

• Purpose: Defines the structure and location of all the different chapters.

• Required Fields:

  • chapters: A dictionary of chapters, where each slug is a chapter.

    • Required Fields:

      • <chapter-slug>: The slug for a chapter.

        • Required Fields:

          • chapter-number: The number order for this chapter.

• Optional Fields:

  • glossary-folder: The name of the glossary folder.

A complete chapter application structure file with multiple chapters may look like the following:

chapters:
  introduction:
    chapter-number: 1
  algorithms:
    chapter-number: 2
glossary-folder: glossary

Chapter Configuration File

• File Name: <chapter-slug>.yaml

• Location: chapters/content/structure/<chapter-slug>/

• Referenced in: chapters/content/structure/structure.yaml

• Purpose: Defines the attributes for a particular chapter.

• Required fields:

  • icon: File path to the icon for the chapter. Icons must be SVG files.

  • sections: File path to the configuration files for sections in the chapter.

• Optional fields:

  • video: URL for the video that appears at the very beginning of the chapter introduction page.

A complete chapter structure file may look like the following:

icon: svg/introduction-icon.svg
sections: sections/sections.yaml

Chapter Sections Configuration File

• File Name: sections.yaml

• Location: chapters/content/structure/<chapter-slug>/sections/

• Referenced in: chapters/content/structure/<chapter-slug>/<chapter-slug>.yaml

• Purpose: Specifiy sections for a chapter and their relative order.

• Required Fields:

  • <section-slug>: Key for the section.

    • Required Fields:

      • section-number: Number order for the section in the chapter.

A complete chapter application structure file with multiple chapters may look like the following:

introduction-for-teachers:
  section-number: 1

further-reading:
  section-number: 2

Curriculum Guides

The curriculum guides application contains teacher guides for incorporating Field Guide material into lessons for particular curricula. The infrastructure is near-identical to that of the Chapters application, so this page will mostly cover what is different.

Curriculum Guides Overview

Much like the chapters application, the curriculum guides application is made up of curriculum guides and each curriculum guide is broken down into sections. The content and configuration files are stored in the same way as those in the Chapters application, with ‘chapter’ equating to ‘curriculum guide’.

What is different?

The most significant differences between the curriculum guides and chapters applications are as follows:

• Interactives cannot be added to curriculum guides.

• Glossary terms cannot be linked to in curriculum guides, as the glossary is a part of the chapters application.

• There is no required icon field in a curriculum guide configuration file.

• There is no optional video field in a curriculum guide configuration file.

Examples

A complete curriculum guide application structure file with multiple curriculum guides may look like the following:

curriculum_guides:
  ncea:
    curriculum-guide-number: 1
  apcsp:
    curriculum-guide-number: 2

A complete curriculum guide structure file may look like the following:

sections: sections/sections.yaml

A complete curriculum guide application structure file with multiple guides may look like the following:

creativity:
  section-number: 1

abstraction:
  section-number: 2

Content Style Guide

These notes are specific to the Computer Science Field Guide project. Be sure to read our general content style guide.

Glossary

The following are added to the glossary and linked to where the words are used:

• All computer science, programming, and mathematical jargon.

• All education jargon.

• All curriculum language that is not broadly used internationally.

Each glossary term has it’s own Markdown file under the csfieldguide/chapters/content/en/glossary/ directory. Here is an example of the Markdown file for the glossary term ‘unicode’:

# Unicode

Unicode is an extension of ASCII; it supports characters from multiple languages, using 16 bits per character.

And here is an example of how to use Verto syntax to link to a glossary term in a chapter:

This is an example of the glossary term {glossary-link term="unicode"}unicode{glossary-link end} being used in a sentence.

This will create a clickable link that reveals the glossary term on the page.

Translations

Getting Started

It’s really easy to start contributing translations using the Computer Science Field Guide

1. Read this documentation page, especially the Translation Notes section.

2. Create an account on Crowdin.

3. Visit the Computer Science Field Guide Crowdin page.

4. Start translating!

Crowdin Overview

We use a localisation management platform called Crowdin for translation of the Computer Science Field Guide. Our project is public, meaning that anyone can create an account and contribute translations.

Crowdin has excellent documentation for translators, and all translators should read the following documents:

• Crowdin Introduction, which provides an overview of the Crowdin platform

• Online Editor, which explains how to use the Crowdin UI to contribute translations.

Translation Phases

There are 3 translation phases used to ensure high quality translation of Computer Science Field Guide content:

1. Translation

2. Proofread

3. Technical Review

In the inital translation phase, anyone (who has created an account with Crowdin) can contribute translations. These translations are then reviewed by a designated proofreader who will check the translations for accuracy and consistency. To request to become a proofreader, please contact one of the Crowdin project managers.

Note

While not enforced by Crowdin, proofreaders should not approve their own translations. Instead, they should be reviewed by a different proofreader.

Finally, a technical review will be performed by a member of the Computer Science Field Guide technical team. In this review, technical components such as Verto tags and document structure will be checked.

Translation notes

Note

On Crowdin, Markdown files are translated on a per-sentence basis. There may be some cases where this is not desirable, and some paragraph level restructuring is required to convey a concept in a given language.

In these cases, it could be possible to work around this with tricks such as

• translating one sentence into the translation box for another.

• translating a sentence into a blank string.

These techniques are highly discouraged as they fight against many aspects of the Crowdin system including

• QA checks that ensure translations match the structure of the source strings.

• Translation memory.

• In context localisation.

• Special Verto tags which are within curly braces { } should not be translated, except for text after alt in an image tag. For example, for the following text:

  {image file-path="img/chapters/parity-trick-cartoon.jpg" alt="The parity magic trick"}
  

  the only text to translate is ‘The parity magic trick’.

If you are unsure how to translate a line, please leave it for another translator.

Developer Documentation

The following pages are for those wanting to develop the Computer Science Field Guide system.

Developer Philosophy

We follow the following philosophy for developing the Computer Science Field Guide project:

We aim to create software that enables authors to easily create, modify, and share education material for the Computer Science Field Guide project.

In short: Think of the author.

This page explains design decisions we made throughout developing the Computer Science Field Guide system.

Configuration Files

We use YAML for storing configuration data of content. It has improved human readability over JSON and XML, especially for authors who have no or little experience with configuration files.

We try to avoid deep nesting (indentation) within configuration files as it’s harder for authors to read nested data. We have split configuration data across multiple configuration files to avoid this issue.

Writing Content

We chose Markdown as the language for text content as it has a great balance between simplicity of writing for authors, and clear structure when converting to HTML.

Django Setup

This page covers the configuration of Django for this project.

Django Overview

We aim to create a clear Django system for ease of development. We are using some advised patterns and practices from Two Scoops of Django - Best Practices for Django 1.8, which include (but is not limited to the following):

• Locking versions of dependencies.

• Django secret settings are loaded from environment variables.

• All templates are located in the templates/ directory.

• The base Django directory, containing settings.py and base urls.py is called config/.

The Django system currently contains the following applications:

• general/ - For general website pages (for example: homepage).

• chapters/ - For chapter content

• interactives/ - For interactive content

Database Structure

The following image shows the relationships between models across all applications within the database.

The rest of the Developer Documentation will inform you of how to develop the applications and other components of the Computer Science Field Guide project.

Loaders

To populate the database with content we have written a series of custom loaders. The loaders for an application are found in the management/commands/ directory, and there is approximately one loader for each configuration file.

Besides populating fields in the database, a loader is also responsible for checking that its corresponding configuration file contains all the required fields, Markdown files are not empty, and icons can be found. If any of these conditions are not met, then an error is thrown.

Errors are defined in utils/errors/ and should aim to be as descriptive and useful as possible as they will most often be read by an author and not necessarily a Python developer.

Website Design (HTML templates/CSS)

This page covers the HTML templates and CSS styling used for the Computer Science Field Guide website.

In summary:

• We use Bootstrap 4 for the underlying framework for responsive design.

• We use SCSS for style sheets where possible.

• We wrap translatable strings in {% trans %} or {% blocktrans %} tags.

• When interactives are viewed in whole page mode they should be centered.

• We aim for the website to be as accessible as possible via accessible features.

Setting Custom Converter Templates

We use Verto to convert Markdown files to HTML. To override a default Verto template, add a new HTML file to utils/custom_converter_templates/<processor-name>.html.

The template file name must correspond to the name of a processor in Verto (for example: image.html, or the name of a supporting template specified in Verto documentation (for example: relative-image-link.html). A list of the available processors is available in the Verto Documentation.

Notes for Writing Custom Converter Templates

All HTML element attributes must contain a value.

The following snippet from a custom template would result in an error:

<details open>

The line would need to be written as this:

<details open="open">

Translation tags must be separate line.

If any Django translation tags are included in a template, it must first be escaped using {{ ' ' }}. For the Django makemessages command to detect the translation tag, the tag must be on its own line (whitespace before the tag doesn’t matter).

The following is an example of how to do this:

<span class="panel-type-title">
    {{-'
        {% trans "Teacher Note" %}
    '-}}
</span>

General Application

The general application manages and serves basic pages for the Computer Science Field Guide website, including (but not limited to):

• Homepage

Appendices Application

The appendices application manages and serves basic pages for the Computer Science Field Guide website, including (but not limited to):

• About page

• Contributors

• Sitemap

Chapters Application

The chapters application is the main focus of the Computer Science Field Guide website, as it contains the majority of educational material for the project.

Note

This guide assumes you’ve read the following documentation:

• Chapters - Provides detail on content in chapters application

• Django Setup - Provides detail of database structure

In general the chapters application is a standard Django application, however it does store and update its associated data for its models uniquely.

Instead of creating and updating model objects through the website (for example: edited by an online editor), the objects are updated by a management script. The content for the chapters application is stored within the contents/ directory, as is run for each deployment of the system. Storing the content within the Git repository gives us greater control over reviewing and accepting proposed changes to content.

The management command for updating the applications data is loadchapters (which is automatically called when running update_data), and can be found at management/commands/loadchapters.py.

Curriculum Guides Application

The curriculum guides application manages and serves curriculum guides. The structure is near-identical to that of the Chapters Application application. For more information consult the author documentation: Curriculum Guides.

Interactives

An interactive is an interactive component on a page. This could be an educational game or demonstration that is created in HTML, CSS, and JavaScript.

This documentation page provides information about the interactive content of the Computer Science Field Guide. Interactives are a great resource for teaching and practicing concepts in the CSFG. The guidelines below aim to keep consistency among interactives. It also allows developers to make modifications to existing interactives with ease.

Interactive Modes

Interactives can be included on a page in three different modes, these are:

• in-page - This is an interactive that is embedded within a page, for example, a chapter section.

• iframe - This is an interactive that is embedded in a chapter by using an iframe. This is used if the interactive is included multiple times in the chapter (to avoid conflicts in JS/CSS).

• whole-page - This in an interactive that is displayed on a new page, which is accessible via a button from the chapter.

An interactive could be displayed with any of the three modes, but generally an interactive is developed with in-page or whole-page as the target usage.

Developing Interactives

Directory Structure

Warning

You should have an understanding of the following concepts before proceeding (we won’t teach you how to do these here, there are plenty of great guides online!):

• HTML

• CSS/SCSS

• JavaScript

• Bootstrap

Every interactive will follow a very similar file structure as given below:

└── csfieldguide/
    ├── static/
    │   ├── interactives/
    │   │   └── <interactive-slug>/
    │   │       ├── scss/
    │   │       │   ├── third-party/
    │   │       │   └── <interactive-slug>.scss
    │   │       ├── img/
    │   │       ├── js/
    │   │       │   ├── third-party/
    │   │       │   └── <interactive-slug>.js
    │   │       ├── package.json
    │   │       └── README.md
    │   ├── js/
    │   │   └── third-party/
    │   └── scss/
    │       └── third-party/
    └── templates/
        └── interactives/
            └── <interactive-slug>.html

Note

Each interactive has a unique slug, which is used in file/directory names and urls. For example the slug for the High Score Boxes interactive is high-score-boxes.

Items of interest from this diagram:

• static/interactives/<interactive-slug>/ – This is the directory where static files for the interactive are stored, which should be broken down into scss, js and img directories.

• static/interactives/<interactive-slug>/package.json – The package.json file is npm’s configuration file for projects and modules. Here we include any dependencies the interactive has. This file should only be included if the interactive loads at least 1 npm module. An example structure of a package.json file for an interactive is below:

  {
    "name": "csfg-interactive-<interactive-slug>",
    "version": "1.0.0",
    "private": true,
    "dependencies": {
        "<module-name>": "<module-version>"
    }
  }
  

  You will need to make sure the path to this file is listed in the csfieldguide/package.json file. More information on npm modules can be found on the Static Files page.

• static/interactives/<interactive-slug>/js/third-party/ – Third-party JavaScript libraries specific to this interactive should be loaded as modules through the package.json file (see above). Add the source JS file to this directory only if it is not possible to load the module through package.json.

• third-party/ – Any third party css or js libraries used in multiple interactives can be stored in static/css/third-party/ and static/js/third-party/ directories.

Warning

Any third-party libraries you include must have a licence that allows them to be used in the CSFG. A summary of the library’s licence must be added to LICENCE-THIRD-PARTY with the full licence file added to cs-field-guide/third-party-licences/.

• static/interactives/<interactive-slug>/README.md – This is a short file that that explains the interactive’s purpose. It can also include links to any documentation or websites that future developers may find useful.

• templates/interactives/<interactive-slug>.html – This is the HTML template for the interactive for a specific locale, as defined in the interactive configuration file. Locale may or may not share a template for an interactive, allowing different versions of an interactive to be available (see GitHub for more information). A template can also be omitted for a locale to disable the interactive for the locale.

  The HTML file should have the following contents:

  {% extends interactive_mode_template %}
  
  {% load i18n %}
  {% load static %}
  
  {% block interactive_html %}
    <!-- The HTML of your interactive goes here -->
  {% endblock interactive_html %}
  
  {% block interactive_css %}
    <!-- The CSS of your interactive goes here. Example of how to link to css file below. -->
    <link rel="stylesheet" href="{% static 'interactives/<interactive-slug>/css/<interactive-slug>.css' %}">
  {% endblock interactive_css %}
  
  {% block interactive_js %}
    <!-- The JavaScript of your interactive goes here. Example of how to link to js file below. -->
    <script type="text/javascript" src="{% static 'interactives/<interactive-slug>/js/<interactive-slug>.js' %}"></script>
  {% endblock interactive_js %}
  

  The first line {% extends interactive_mode_template %} is required for all interactives. The second line {% load i18n %} is needed if there is translatable text in the template. The third line {% load static %} allows us to serve additional files such as images, JavaScript or CSS. These are referred to as “static files” in Django.

We recommend looking at existing interactives and how their files are organised to become familiar with developing your own interactive.

Interactive Requirements

A completed interactive requires the following to be included into the repository for release:

• A README.md file explaining the interactive, linking to any documentation or websites that future developers may find useful. Uninteractives generally don’t have a README.md file unless future developers may find it useful.

• Extra libraries/scripts that have been used have been used and attributed correctly.

• Be easily accessible on desktop and mobile, or show a disclaimer that it is suited for desktop use only.

• Abides by the repository contribution style guidelines.

• Must work in browsers updated within the last year. Therefore try and avoid experimental features but don’t worry about supporting older browsers (but it’s great if it can!).

Adding Interactives

Once you have developed your interactive (see Developing Interactives), it’s time to add it to a page. This includes embedding the interactive in the chapter text (see Interactive (Verto feature)).

Note

When adding an interactive using the Verto syntax, note that Verto uses the term name, this is actually referring to the slug of the interactive.

The interactive will also need to be added to the list of interactives in the interactive configuration file (see below).

Interactive Configuration Files

• File Name: interactives.yaml

• Location: interactives/content/structure/

• Purpose: Defines the list of interactives in the Field Guide.

• Required Fields:

  • A dictionary of all interactive data, where each key is a slug for an interactive.

  • The dictionary of interactive data must include:

    • languages: A dictionary of all languages the interactive is available in, where each key is the locale.

    • is_interactive: This field was introduced so we could distingush between interactives and uninteractives. If the is_interactive field is set to false, it is not displayed in the interactives appendix. It means the user cannot interact with it to the extent where it would be useful to have as a standalone feature.

  • The dictionary of interactive data can also include:

    • use_large_thumbnail: An optional field that should only be included if set to true. If the use_large_thumbnail field is set to true, the thumbnail generator will use a window 75% larger than normal to generate the thumbnail. This is useful for interactives that cannot be properly displayed at the normal window size. However, this feature should be used sparingly and avoided if possible.

A complete interactive structure file may look like the following:

number-memory:
  languages:
    en: interactives/number-memory.html
  is_interactive: true
off-by-one:
  languages:
    en: interactives/off-by-one.html
    de: interactives/off-by-one.html
    es: interactives/off-by-one.html
  is_interactive: false
packet-attack:
  languages:
    en: interactives/packet-attack.html
  is_interactive: true
  use_large_thumbnail: true

Every interactive must also have a YAML file within each locale containing the names of the interactives, in the language for that particular locale.

The translation YAML file:

• Is in: interactives/content/<locale>/

• Is called: interactives.yaml

• Contains: Provides names of all interactives. Every interactive slug present in the interactive structure file must be present in each locale’s translation file.

  For example,

  number-memory:
    name: Number Memory
  off-by-one:
    name: Off By One
  packet-attack:
    name: Packet Attack
  

Uninteractives

Uninteractives follow the exact same structure as interactives, the biggest difference is that they are not designed to be interacted with. They are most commonly used as a replacement for images with text we want translated. Uninteractives are distinguished from interactives by setting the is_interactive: attribute to false in the interactives.yaml configuration file. Uninteractives are not displayed in the interactives appendix, and no thumbnails are generated for them.

Static Files

The static files (images, CSS, JavaScript, etc) used within the website go through the following steps:

1. Files are stored within the static directory.

2. Files are processed with a Gulpfile into the build directory with ./dev static or ./dev static_prod.

3. Files are collected into the staticfiles directory with ./dev collect_static.

Note that files under the static/ folder are editable and the files under the staticfiles/ folder are generated and should not be edited. Every interactive has a generated thumbnail stored in staticfiles/img/interactives/thumbnails/. These can be created with ./dev make_interactive_thumbnails. You will need to run the ./dev collect_static command after for them to appear in the staticfiles/ directory.

JavaScript Files

JavaScript files are processed with Browserify to allow loading modules from NPM.

Any modules used must be listed with a package.json file within the directory, with the package.json file listed in the csfieldguide/package.json file (see examples already within this file).

If you wish to not apply optimisation steps (Browserify, minification, etc), then list the files within the js_files_skip_optimisation constant within csfieldguide/gulpfile.js.

Any files within the csfieldguide/static/js/modules/ directory are skipped by the Gulpfile and not processed by themselves. Module files can be required by other JavaScript files to be included.

If NPM modules are added, modified, or deleted, the Docker images will need to be rebuilt using ./dev build node.

Django’s JavaScript translation catalog enables the use of gettext() in JavaScript files to translate text. The JavaScript translation files are prepared before server start.

Node dependencies

Multiple sets of Node dependencies are installed throughout the project using package.json files. This includes a high level package.json file for website dependencies at csfieldguide/, and then more package.json files within the csfieldguide/static/interactives/ directory.

We have chosen to install Node dependencies within the Docker container, however we have the installed dependencies excluded from the Docker Compose volume that maps the developer’s local directory within the container.

Each separate node_modules is specified individually (within docker-compose.local.yml and infrastructure/local/django/Dockerfile), as the Docker volume of the website dependencies (would be csfieldguide/node_modules) would hide the node_modules directory for each interactive’s dependencies, therefore resulting in interactives looking at the top level node_modules directory for dependencies.` This meant that some interactives were using versions on dependencies that they were not intended for.

Test Suite

Running the Test Suite

./dev test_suite will run the entire test suite.

./dev test_specific <module> will run a specific module of tests, for example, ./dev test_specific tests.appendices.views will run all the views test for appendices.

All tests are in the csfieldguide/tests/ directory, which mirrors the structure of the csfieldguide/ directory with directories matching the installed Django applications.

Note that each application being tested has it’s own folder, and this is then broken down further into the component being tested (i.e. views, urls, models, etc).

Items of interest from this diagram:

• models/ - contains a test file for each model in the app.

• urls/ - contains a test file for each url in the app.

• views/ - contains a test file for each view in the app.

• loaders/ - contains a test file for each loader in the app as well as an assets/ directory. Test yaml files should be saved in the corresponding loader directory within assets/ and should mimick the folder structure of the app where necessary.

• Test Data Generators - these are classes used to generate place holder data in the database. You should use the methods in these files when testing a model that contains a foreign key and/or many-to-many field that needs to be populated.

• BaseTestWithDB.py - this class inherits the Django TestCase class, and creates and logs in a user. This is the base test class that all other tests should inherit from in order to interact with the database.

• utils/errors/ - contains test error classes for testing exceptions are raised correctly by the loaders.

Adding Tests

When writing a new test function, it is important that the method name is as descriptive as possible. The method name should also be prefixed with test_ as the test suite will only execute methods with this prefix.

Note

We use Codecov to check the coverage of our tests. Ideally each pull request should cover 100% of the changes (therefore increasing the total project coverage).

Troubleshooting

dev helper script

I get a No such file or directory error when running the dev script

Check your terminal working directory is within the cs-field-guide directory, the root directory of the project. Running the ls command in this directory should list the dev file.

I have an error when running ./dev start

If you are having issues running the start command, try rebuilding the system images with ./dev build. Changes may be have been made to the system images since you initally created them.

If issue still persists, log a bug on our issue tracker.

Viewing website

Images are not displayed when I view the website

Firstly check the image is located in the staticfiles/ directory. If the image isn’t located within the directory, check the original image is located within the static directory.

If the image is located within the static/ directory, check the filepath is correct. When running ./dev update, the script will report an error if an image cannot be found.

Changed CSS/SCSS styles are not updated when I view the website

Check the logs of the Node container processing the static files with ./dev logs -f node.

The website isn’t displaying when I open cs-field-guide.localhost in a browser

Check you have run both the ./dev start and ./dev update commands (in that order), and that it hasn’t reported any errors.

Changelog

This page lists updates to the Computer Science Field Guide. All notable changes to this project will be documented in this file.

Note

We base our numbering system from the guidelines at Semantic Versioning 2.0.0, however since our project started before it was migrated to GitHub, the first open source release is being labeled as 2.0.0.

Given a version number MAJOR.MINOR.HOTFIX:

• MAJOR version change when system-wide modifications incompatible with previous versions are made (for example: switching to a new backend system).

• MINOR version change when content or functionality is added or updated (for example: new chapter, new interactive, large number of text (typo/grammar) fixes).

• HOTFIX version change when bug hotfixes are made (for example: fixing a typo, fixing a bug in an interactive).

• A pre-release version is denoted by appending a hyphen and the alpha label followed by the pre-release version.

We have listed major changes for each release below. All downloads are available on GitHub

3.13.0

Release date: 15th December 2022

Changelog:

• Add section about Shannon’s Experiment to the Compression chapter.

• Add more comprehensive Getting Started documentation.

• Add an “Adding a chapter” section to the Author Documentation.

• Update infrastructure to fix issues with local development on multi-user Linux machines.

• Fix majority of loading bugs caused by the 3.12.6 release.

• Core dependency changes:

  • Update crowdin/github-action from 1.5.0 to 1.5.2

  • Update decode-uri-component from 0.2.0 to 0.2.2

  • Update dependabot/fetch-metadata from v1.3.4 to v1.3.5

  • Update django-debug-toolbar from 3.7.0 to 3.8.1

  • Update django-modeltranslation from 0.18.5 to 0.18.7

  • Update engine.io from 6.2.0 to 6.2.1

  • Update jquery from 3.6.1 to 3.6.2

  • Update lxml from 4.9.1 to 4.9.2

  • Update postcss from 8.4.18 to 8.4.20

  • Update sass from 1.55.0 to 1.56.2

  • Update selenium from 4.5.0 to 4.7.0

  • Update socket.io-parser from 4.0.4 to 4.0.5

  • Update sphinx-rtd-theme from 1.1.0 to 1.1.1

  • Update yargs from 17.6.0 to 17.6.2

• Interactive scene-editor dependency changes:

  • Update three from 0.146.0 to 0.147.0

3.12.6

Release date: 3rd November 2022

Changelog:

• Update content rather than recreating it when update_data script is run.

• Dependency updates:

  • Update crowdin/github-action from 1.4.16 to 1.5.0.

  • Update sphinx-rtd-theme from 1.0.0 to 1.1.0.

3.12.5

Release date: 31st October 2022

Changelog:

• Fix bug where rgb-mixer interactive couldn’t load required CSS file.

• Dependency updates:

  • Update cssnano from 5.1.13 to 5.1.14.

3.12.4

Release date: 31st October 2022

Changelog:

• Add abiltiy to set initial zoom level in pixel-viewer interactive via URL parameter.

• Remove broken documentation link.

• Disable healthcheck on Docker task service to prevent deletion while running.

3.12.3

Release date: 29th October 2022

Changelog:

• Add abiltiy to hide pixel colour codes in pixel-viewer interactive via URL parameter.

• Fix bug where imported package CSS files were not imported.

• Fix bug where pixel-viewer interactive isn’t sized correctly when embedded via iframe.

• Replaced deprecation method in matrix-simplifier interactive.

• Update analytics to Plausible.

• Rewrite documentation to project specific content, and linking to general UCCSER documentation where required.

• Display white favicon when browser dark theme is used. #1957

• Add project logo variants with text.

• Core dependency changes:

  • Update autoprefixer from 10.4.12 to 10.4.13.

  • Update crowdin/github-action from 1.4.15 to 1.4.16.

  • Update cssselect from 1.1.0 to 1.2.0.

  • Update django from 3.2.15 to 3.2.16.

  • Update psycopg2 from 2.9.4 to 2.9.5.

• Interactive scene-editor dependency changes:

  • Update three from 0.145.0 to 0.146.0.

3.12.2

Release date: 20th October 2022

Changelog:

• Add ability to hide mode headings and initial text in Parity interactive.

• Add ability to circle a row and column in Parity interactive by clicking on a grid reference label (or where they would be if they’re hidden).

• Fix bug where edges of barcode where visible in the Product Code Check Digit Calculation interactive when embedded. #1965

• Modify Docker deployment workflow to be in line with UCCSER repositories. #1971

3.12.1

Release date: 19th October 2022

Changelog:

• Allow QR Code Generator interactive controls to be hidden via URL parameter.

• Allow Parity interactive settings be changed via URL parameter, including setting grid size, presetting intial bit values, hiding controls, and showing grid references.

• Core dependency changes:

  • Update crowdin/github-action from 1.4.14 to 1.4.15.

  • Update django-modeltranslation from 0.18.4 to 0.18.5.

  • Update docker/build-push-action from 3.1.1 to 3.2.0.

  • Update docker/login-action from 2.0.0 to 2.1.0.

  • Update postcss from 8.4.17 to 8.4.18.

  • Update sphinx from 5.2.3 to 5.3.0.

3.12.0

Release date: 11th October 2022

Changelog:

• Add Product Code Check Digit Calculation interactive.

• Add QR Code Generator interactive.

• Rename Shannan Experiment interactive to Shannon’s prediction and entropy of printed text experiment.

• Fix bug where interactive NPM dependecies were being overriden by base NPM dependencies. Interactive dependencies have been updated accordingly.

• Remove FSA dependency with simplified JavaScript solution.

• Core dependency changes:

  • Update autoprefixer from 10.4.8 to 10.4.12.

  • Update coverage from 6.4.4 to 6.5.0.

  • Update crowdin/github-action from 1.4.12 to 1.4.14.

  • Update dependabot/fetch-metadata from v1.3.3 to v1.3.4.

  • Update django-debug-toolbar from 3.6.0 to 3.7.0.

  • Update node from 14.19.0-buster to 14.20.0-buster.

  • Update postcss from 8.4.16 to 8.4.17.

  • Update psycopg2 from 2.9.3 to 2.9.4.

  • Update sass from 1.54.5 to 1.55.0.

  • Update selenium from 4.4.0 to 4.5.0.

  • Update sphinx 5.1.1 to 5.2.3.

  • Update uniseg from 0.7.1.post2 to 0.7.2.

  • Update yargs from 17.5.1 to 17.6.0.

• Interactive city-trip dependency changes:

  • Update cytoscape from 3.22.1 to 3.23.0.

• Interactive product-code-check-digit-calculation dependency changes:

  • Add arrows-svg 1.5.6.

  • Add jsbarcode 3.11.5.

• Interactive qr-code-generator dependency changes:

  • Add qrcode-generator 1.4.4.

• Interactive scene-editor dependency changes:

  • Update three from 0.143.0 to 0.145.0.

  • Add sprintf-js 1.1.2 (to be independent from base package.json file).

• Interactive shannon-experiment dependency changes:

  • Add chart.js 3.9.1.

3.11.0

Release date: 30th August 2022

Changelog:

• Add Shannon Experiment interactive prototype.

• Update Computer Security URLs and typo. #1913

• Fix outdated references to interactive. #1902

• Fix issue where items on the top navigation bar couldn’t fit on one line on small screens.

• Update project to use uccser-development-stack v3.

• Show full Git SHA on development website.

• Add OCI labels to Django Docker image.

• Update Traefik middleware to use a unique name in production deployment.

• Fix bug preventing translation pipeline from completing.

• Core dependency changes:

  • Add gulp-dependents 1.2.5.

  • Update autoprefixer from 10.4.7 to 10.4.8.

  • Update bootstrap from 4.6.1 to 4.6.2.

  • Update coverage from 6.4.1 to 6.4.4.

  • Update crowdin/github-action from 1.4.9 to 1.4.12.

  • Update cssnano from 5.1.12 to 5.1.13.

  • Update django from 3.2.14 to 3.2.15.

  • Update django-debug-toolbar from 3.4.0 to 3.6.0.

  • Update django-modeltranslation from 0.18.2 to 0.18.4.

  • Update django-statici18n from 2.2.0 to 2.3.1.

  • Update docker/build-push-action from v3.0.0 to v3.1.1.

  • Update jquery from 3.6.0 to 3.6.1.

  • Update postcss from 8.4.14 to 8.4.16.

  • Update postgres from 13.3 tp 13.8.

  • Update Pygments from 2.12.0 to 2.13.0.

  • Update sass from 1.53.0 to 1.54.5.

  • Update selenium from 4.3.0 to 4.4.0.

  • Update sphinx from 5.0.2 to 5.1.1.

  • Remove urijs.

• Interactive big-number-calculator dependency changes:

  • Update big.js from 6.2.0 to 6.2.1.

• Interactive bin-packing dependency changes:

  • Update interactjs from 1.10.14 to 1.10.17.

• Interactive box-rotation dependency changes:

  • Update three from 0.142.0 to 0.143.0.

• Interactive box-translation dependency changes:

  • Update three from 0.142.0 to 0.143.0.

• Interactive city-trip dependency changes:

  • Update cytoscape from 3.21.2 to 3.22.1.

• Interactive jpeg-compression dependency changes:

  • Update interactjs from 1.10.14 to 1.10.17.

• Interactive scene-editor dependency changes:

  • Update three from 0.142.0 to 0.143.0.

• Interactive unicode-binary dependency changes:

  • Remove urijs.

• Interactive viola-jones-face-detector dependency changes:

  • Update interactjs from 1.10.14 to 1.10.17.

3.10.2

Release date: 6th July 2022

Changelog:

• Update Trainsylvania interactives imagery and station names.

• Combine trainsylvania-blank and trainsylvania-complete into trainsylvania-map interactive.

• Remove trainsylvania blank map file in favor of trainsylvania-map interactive.

• Add options to binary-cards interactive for hiding UI elements and displaying right to left.

• Fix bug where scene-editor interactive wasn’t working. #1837

• Fix indentation within Dependabot configuration file.

• Fix Gulp watch task to watch correct files.

• Add attribution to texture used in scene-editor interactive.

• Update Gulp JS task to only update files changed since last run.

• Core dependency changes:

  • Update dependabot/fetch-metadata from v1.3.1 to v1.3.3.

  • Update django from 3.2.13 to 3.2.14.

  • Update lxml from 4.9.0 to 4.9.1.

• Interactive box-rotation dependency changes:

  • Update three from 0.141.0 to 0.142.0.

• Interactive box-translation dependency changes:

  • Update three from 0.141.0 to 0.142.0.

• Interactive scene-editor dependency changes:

  • Update three from 0.141.0 to 0.142.0.

3.10.1

Release date: 28th June 2022

Changelog:

• Add search functionality for English language.

• Updates to binary cards interactive:

  • Only creates card elements as required.

  • Fixes bug with defining number of cards.

  • Allows card total to be toggled or hidden.

• Remove broken link in the Images and Colours section witin the Data Representation chapter.

• Update glossary definition of Algorithm.

• Allow centered interactives to be embedded anywhere (this will likely change in the future to be restricted only to UCCSER domains).

• Add permalinks to glossary page entries.

• Fix bug where interactive thumbnails were missing assets during creation. #1745

• Fix bug where CFG Parser examples weren’t loaded. #1789

• Update test coverage to codecov.

• Suppress gunicorn access and error logs during local development.

• Auto-merge minor dependency updates (this includes minor and patch updates).

• Allow all dependency update pull requests to be created (remove open limit on Dependabot).

• Ignore updates to non-LTS Django packages.

• Core dependency changes:

  • Update actions/checkout from v2 to v3.

  • Update actions/download-artifact from v2 to v3.

  • Update actions/setup-python from v2 to v4.

  • Update actions/upload-artifact from v2 to v3.

  • Update ansi-colours from 4.1.1 to 4.1.3.

  • Update autoprefixer from 10.3.7 to 10.4.7.

  • Update browser-sync from 2.27.5 to 2.27.10.

  • Update codemirror from 5.65.0 to 5.65.6.

  • Update coverage from 6.2 to 6.4.1.

  • Update crowdin/github-action from 1.4.7 to 1.4.9.

  • Update cssnano from 5.0.8 to 5.1.12.

  • Update django from 3.2.12 to 3.2.13.

  • Update django-cors-headers from 3.11.0 to 3.13.0.

  • Update django-debug-toolbar from 3.2.4 to 3.4.0.

  • Update django-environ from 0.8.1 to 0.9.0.

  • Update django-modeltranslation from 0.17.3 to 0.18.2.

  • Update docker/build-push-action from v2.9.0 to v3.0.0.

  • Update docker/build-push-action from v2.9.0 to v3.0.0.

  • Update docker/login-action from v1.13.0 to v2.0.0.

  • Update docker/metadata-action from v3 to v4.

  • Update fancy-log from 1.3.3 to 2.0.0.

  • Update flake8 from 3.9.2 to 4.0.1.

  • Update gulp-sass from 5.0.0 to 5.1.0.

  • Update lxml from 4.8.0 to 4.9.0.

  • Update postcss 8.4.5 to 8.4.14.

  • Update Pygments from 2.11.2 to 2.12.0.

  • Update sass from 1.49.8 to 1.53.0.

  • Update selenium from 4.1.1 to 4.3.0.

  • Update sphinx from 4.4.0 to 5.0.2.

  • Update whitenoise from 6.0.0 to 6.2.0.

  • Update yargs from 10.3.1 to 10.5.1.

  • Remove intro.js 4.2.2.

• Interactive big-number-calculator dependency changes:

  • Update big.js from 5.1.2 to 6.2.0.

• Interactive bin-packing dependency changes:

  • Update interactjs from 1.10.11 to 1.10.14.

• Interactive box-rotation dependency changes:

  • Update three from 0.138.0 to 0.141.0.

  • Update @tweenjs/tween.js from 17.3.0 to 18.6.4.

• Interactive box-translation dependency changes:

  • Update three from 0.138.0 to 0.141.0.

  • Update @tweenjs/tween.js from 17.3.0 to 18.6.4.

• Interactive city-trip dependency changes:

  • Update cytoscape from 3.21.0 to 3.21.2.

• Interactive frequency-analysis dependency changes:

  • Update es5-shim from 4.6.5 to 4.6.7.

• Interactive jpeg-compression dependency changes:

  • Update interactjs from 1.10.11 to 1.10.14.

• Interactive scene-editor dependency changes:

  • Update three from 0.138.0 to 0.141.0.

• Interactive unicode-binary dependency changes:

  • Update urijs from 1.19.8 to 1.19.11.

  • Update string.fromcodepoint from 0.2.1 to 1.0.0.

• Interactive unicode-chars dependency changes:

  • Update string.fromcodepoint from 0.2.1 to 1.0.0.

• Interactive viola-jones-face-detector dependency changes:

  • Update interactjs from 1.10.11 to 1.10.14.

3.10.0

Release date: 31st March 2022

Changelog:

• Add new chapter ‘Computer Security’.

  • The chapter only contains text currently, images and interactives will be added at a later time.

• Minor text changes (e.g. grammar corrections) in ‘Grammars and Parsing’ section.

• Add glossary definitions for:

  • Terminal

  • Non-terminal

  • Production

• Add new panel type ‘Exercise’.

• Fix alignment of panels within a nested list.

• Show chapter section name in browser title.

• Increase size of context-free grammar parsing challenge working box.

• Improve interface when context-free grammar parsing challenge has examples.

• Change relative links within chapter and chapter section text to open in a new tab.

• Remove search functionality, due to high costs and no user usage.

• Dependency changes:

  • Remove django-haystack[elasticsearch] 3.1.1.

  • Remove elasticsearch 5.5.3.

  • Remove django-widget-tweaks 1.4.8.

3.9.0

Release date: 26th February 2022

Summary of changes:

This release adds new content on grammars and parsing, QR codes, Fitts’ law, and other ways to represent FSAs.

Changelog:

• Add new section in ‘Formal Languages’ chapter on ‘Grammars and Parsing’.

• Add new section in ‘Coding - Error Control’ chapter on ‘QR codes’.

• Add new section in ‘Human Computer Interaction’ chapter on ‘Pointing at things: Fitts’ Law’

• Add new content in ‘Finite State Automata’ section on ‘Other ways to represent finite state automata’.

• Add seven new interactives for new and upcoming content:

  • Fitts’ law

  • Clicking with shaking

  • Index of difficulty calculator

  • Plane turbulence

  • Firewall sorting

  • Password strength - Brute force variant

  • Password strength - Dictionary attack variant

• Update definition of ‘Parse tree’ in glossary.

• Fix broken link to padding in cryptography Wikipedia page.

• Update ‘CFG Parsing Challenge’ interactive:

  • Disable the text field that allows customising the equation text, as it’s prone to errors. This can be re-enabled with the URL parameter editable-target.

  • Modify ‘New productions’ button to ‘Customise productions’, and lower it’s priority in the interactive. The productions menu is also prefilled with the currently loaded exercise. This can be disabled with the URL parameter hide-builder.

  • Increase average difficulty of random equations.

  • Update terms used for user prompts.

• Update ‘NFA Guesser’ interactive:

  • Allow answer to be optionally viewed after multiple failed attempts.

  • Change answer options to match appearance in NFA map.

• Update ‘Parity Trick’ interactive:

  • Add optional grid references.

• Fix incorrect solution for representing ‘water’ as binary.

• Add tracking of dependencies within interactives using Dependabot.

• Modify command names to be consistent across UCCSER projects.

• Remove resource links to websites that do not exist anymore.

• Add open/close symbols and types titles (for example ‘Curiosity’) on panels. Panels can also be forced to be always open.

• Pause of playing Vimeo video within a closed panel.

• Add URL for website status information.

• Open button links in a new tab.

• Fix bug where translation files were not generated.

• Allow build helper command to pass parameters.

• Allow translations of words within custom Verto templates.

• Update interactive template block names to avoid overriding.

• Add notes to documentation on writing custom Verto templates.

• Change recommended JavaScript indentation to 4 spaces from 2 spaces. Existing code has not be updated.

• Modify URL parameter decoder to accept equal signs within a parameter.

• Enable CORS headers for providing version information across domains.

• Add templatetag for reading file to template.

• Add syntax highlighting within code blocks.

• Change environment variable to allow wider Traefik router variations.

• Update SCSS division symbol away from deprecated ‘/’ symbol.

• Update logging configuration.

• Add package-lock.json file.

• Core dependency changes:

  • Add django-cors-headers 3.11.0.

  • Add Pygments 2.11.2.

  • Update bootstrap from 4.6.0 to 4.6.1.

  • Update codemirror from 5.63.1 to 5.65.0.

  • Update coverage from 5.5 to 6.2.

  • Update crowdin/github-action from 1.4.0 to 1.4.7.

  • Update django from 3.2.8 to 3.2.12.

  • Update django-debug-toolbar from 3.2.2 to 3.2.4.

  • Update django-environ from 0.7.0 to 0.8.1.

  • Update django-statici18n from 2.0.1 to 2.2.0.

  • Update docker/build-push-action from 2.7.0 to 2.9.0.

  • Update docker/login-action from 1.10.0 to 1.13.0.

  • Update lxml from 4.6.3 to 4.8.0.

  • Update MathJax from 2.7.5 to 2.7.9.

  • Update Node 14.17.0 to 14.19.0.

  • Update postcss from 8.3.9 to 8.4.5.

  • Update psycopg2 from 2.9.1 to 2.9.3.

  • Update sass from 1.42.1 to 1.49.8.

  • Update selenium omfr 3.141.0 to 4.1.1.

  • Update sphinx from 4.2.0 to 4.4.0.

  • Update whitenoise from 5.3.0 to 6.0.0.

  • Update yargs from 17.2.1 to 17.3.1.

• Interactive bin-packing dependency changes:

  • Update interactjs from 1.4.0-alpha.17 to 1.10.11.

• Interactive box-rotation dependency changes:

  • Update three from 0.101.1 to 0.138.0.

• Interactive box-translation dependency changes:

  • Update three from 0.101.1 to 0.138.0.

• Interactive city-trip dependency changes:

  • Update cytoscape from 3.4.2 to 3.21.0.

  • Update cytoscape-automove from 1.10.1 to 1.10.3.

• Interactive colour-matcher dependency changes:

  • Update wnumb from 1.1.0 to 1.2.0.

• Interactive frequency-analysis dependency changes:

  • Update es5-shim from 4.5.12 to 4.6.5.

  • Update es6-shim from 0.35.4 to 0.35.6.

• Interactive jpeg-compression dependency changes:

  • Update dct from 0.0.3 to 0.1.0.

  • Update interactjs from 1.4.0-alpha.17 to 1.10.111.

• Interactive matrix-simplifier dependency changes:

  • Update dragula from 3.7.2 to 3.7.3.

• Interactive packet-attack dependency changes:

  • Update phaser from 3.16.2 to 3.55.2.

• Interactive python-interpreter dependency changes:

  • Update skulpt from 0.11.1 to 1.2.0.

• Interactive rsa-decryption dependency changes:

  • Update big-integer from 1.6.44 to 1.6.51.

  • Update node-rsa from 1.0.5 to 1.1.1.

• Interactive rsa-encryption dependency changes:

  • Update big-integer from 1.6.44 to 1.6.51.

  • Update node-rsa from 1.0.5 to 1.1.1.

• Interactive rsa-key-generator dependency changes:

  • Update node-rsa from 1.0.5 to 1.1.1.

• Interactive scene-editor dependency changes:

  • Update three from 0.108.0 to 0.138.0.

• Interactive sorting-algorithms dependency changes:

  • Update dragula from 3.7.2 to 3.7.3.

• Interactive unicode-binary dependency changes:

  • Update urijs from 1.19.1 to 1.19.8.

  • Update underscore.string from 3.3.5 to 3.3.6.

• Interactive viola-jones-face-detector dependency changes:

  • Update interactjs from 1.4.0 to 1.10.11.

3.8.5

Release date: 6th October 2021

Changelog:

• Fix bug where interactives in chapters were not displaying.

• Redirect non-www requests to www subdomain at Traefik router.

• Run migration commands in existing container to allow access to created files.

• Remove Docker compose volumes to avoid issues with development.

• Dependency changes:

  • Update autoprefixer from 10.3.6 to 10.3.7.

  • Update codemirror from 5.62.3 to 5.63.1.

  • Update django from 3.2.7 to 3.2.8.

  • Update gulp-postcss from 2.0.1 to 2.1.0.

  • Update postcss from 8.3.6 to 8.3.9.

  • Update yargs from 17.1.1 to 17.2.1.

3.8.4

Release date: 29th September 2021

Changelog:

• Allow greater customisation for the website’s Traefik routing rule.

3.8.3

Release date: 28th September 2021

Changelog:

• Rebuild search index when updating data, instead of application start.

• Modify configuration for Docker Swarm services to specify updatedata task.

• Dependency changes:

  • Update crowdin/github-action from 1.3.2 to 1.4.0.

  • Update autoprefixer from 10.3.2 to 10.3.6.

  • Update intro.js from 4.1.0 to 4.2.2.

  • Update sass from 1.38.0 to 1.42.1.

  • Update sphinx from 4.1.2 to 4.2.1.

  • Update sphinx-rtd-theme from 0.5.2 to 1.0.0.

  • Update django from 3.2.6 to 3.2.7.

  • Update django-environ from 0.4.5 to 0.7.0.

  • Update django-haystack[elasticsearch] from 3.0 to 3.1.1.

3.8.2

Release date: 6th September 2021

Changelog:

• Modify network name for production deployments.

3.8.1

Release date: 28th August 2021

Changelog:

• Fix encoding of JPG image that prevented minifying.

• Modify workflow to only produce production docker image run on published release.

3.8.0

Release date: 25th August 2021

Changelog:

• Move website from Google Cloud Platform to Docker Swarm hosted at the University of Canterbury. #1380

  • Modifies website infrastructure to use Docker Swarm, running all website components as services.

  • Use GitHub actions for automated workflows. This includes testing, deployment, and internationalisation jobs.

  • Simplify static file pipeline, runs as separate service.

• Switch to GitHub dependency manager.

• New Depth section for Computer Vision chapter:

  • Includes new Depth from Stereo Vision interactive. #1375

• Update Context-free Grammar interactive to always generate valid expressions via brute force, and improve the interface with a history log and consistent formatting.

• Allow Big Number Calculator to calculate numbers with low digit counts. #1340

• Dependency changes:

  • Add ansi-colors 4.1.1.

  • Add browser-sync 2.27.5.

  • Add child_process 1.0.2.

  • Add cssnano 5.0.8.

  • Add django-bootstrap-breadcrumbs 0.9.2.

  • Add elasticsearch 5.5.3.

  • Add fancy-log 1.3.3.

  • Add got 11.8.2.

  • Add gulp-concat 2.6.1.

  • Add gulp-imagemin 7.1.0.

  • Add intro.js 4.1.0.

  • Add lity 2.4.1.

  • Add pixrem 5.0.0.

  • Add postcss 8.3.6.

  • Add sass 1.38.0.

  • Add whitenoise 5.0.3.

  • Remove @babel/core 7.1.2

  • Remove @babel/preset-env 7.1.0

  • Remove del 3.0.0

  • Remove featherlight 1.7.13

  • Remove gevent 1.4.0.

  • Remove gulp-babel 8.0.0

  • Remove gulp-jshint 2.1.0

  • Remove gulp-notify 3.2.0

  • Remove gulp-util 3.0.8

  • Remove gulplog 1.0.0

  • Remove gumshoejs 5.1.2

  • Remove jshint 2.9.6.

  • Remove jshint-stylish 2.2.1.

  • Remove node-gyp 3.8.0

  • Remove Pillow 7.2.0.

  • Remove request 2.88.0

  • Remove run-sequence 2.2.1

  • Remove sticky-state 2.4.1

  • Remove wheel 0.35.1.

  • Remove Whoosh 2.7.4.

  • Update autoprefixer from 9.3.1 to 10.3.2.

  • Update bootstrap from 4.3.1 to 4.6.0.

  • Update browserify from 16.2.2 to 17.0.0.

  • Update codemirror from 5.42.0 to 5.62.3.

  • Update coverage from 5.3 to 5.5.

  • Update details-element-polyfill from 2.3.1 to 2.4.0.

  • Update django from 2.2.3 to 3.2.6.

  • Update django-debug-toolbar from 3.1.1 to 3.2.2.

  • Update django-haystack 3.0 to django-haystack[elasticsearch] 3.0.

  • Update django-modeltranslation from 0.15.2 to 0.17.3.

  • Update django-statici18n from 1.9.0 to 2.0.1.

  • Update flake8 from 3.8.4 to 3.9.2

  • Update gulp from 3.9.1 to 4.0.2.

  • Update gulp-filter from 5.1.0 to 7.0.0.

  • Update gulp-if from 2.0.2 to 3.0.0.

  • Update gulp-postcss from 7.0.1 to 9.0.0.

  • Update gulp-rename from 1.4.0 to 2.0.0.

  • Update gulp-sass from 4.0.2 to 5.0.0.

  • Update gulp-sourcemaps from 2.6.4 to 3.0.0.

  • Update gulp-tap from 1.0.1 to 2.0.0.

  • Update gulp-terser from 1.1.5 to 2.0.1.

  • Update gunicorn from 19.9.0 to 20.1.0.

  • Update iframe-resizer from 4.1.1 to 4.3.2.

  • Update jquery from 3.4.1 to 3.6.0.

  • Update lxml from 4.6.2 to 4.6.3.

  • Update multiple-select from 1.2.1 to 1.5.2.

  • Update popper.js from 1.15.0 to 1.16.1.

  • Update postcss-flexbugs-fixes from 4.1.0 to 5.0.2.

  • Update Postgres database from 9.6 to 13.3.

  • Update psycopg2 from 2.7.6.1 to 2.9.1.

  • Update puppeteer from 1.9.0 to Docker image 10.0.0.

  • Update pydocstyle from 5.1.1 to 6.1.1.

  • Update PyYAML from 5.3.1 to 5.4.1.

  • Update sphinx from 3.3.0 to 4.1.2.

  • Update sphinx-rtd-theme from 0.5.0 to 0.5.2.

  • Update uniseg from 0.7.1 to 0.7.1.post2.

  • Update verto 0.11.0 to 1.0.1.

  • Update yargs from 12.0.2 to 17.1.1.

3.7.0

Release date: 2nd February 2021

Changelog:

• Add context-free grammar interactive. #1364

• Update the list of editors. #1361

3.6.0

Release date: 11th January 2021

Changelog:

• Improve consistency of the URL parameters for the RGB Mixer interactive: #1309

• Update CMY Mixer interactive to be consistent with RGB Mixer: #1306

• Improve limitations of the Algorithm Timer interactive: #1332

• Replace broken link in the HCI chapter: #1316

• Fix typos: #1320 #1358

• Dependency updates:

  • Update lxml from 4.5.2 to 4.6.2.

  • Update wheel from 0.34.2 to 0.35.1.

  • Update django-haystack from 2.8.1 to 3.0.

  • Update django-modeltranslation from 0.15.1 to 0.15.2.

  • Update sphinx from 3.1.2 to 3.3.0.

  • Update django-debug-toolbar from 2.2 to 3.1.1.

  • Update flake8 from 3.8.3 to 3.8.4.

  • Update pydocstyle from 5.0.2 to 5.1.1.

  • Update coverage from 5.2.1 to 5.3.

3.5.1

Release date: 1st August 2020

Changelog:

• Add URL redirects for CS Unplugged Pixelmania activity. #1303

• Update Pixel Viewer interactive: #1300 #1302 #1304

  • Add brightness value mode.

  • Add ability to zoom to specific starting point for an image.

  • Set image when zooming to be pixelated (only on modern browsers).

  • Add parameter to hide mode selector.

  • Add parameter to hide value type selector.

  • Add parameter to show Pixelmania branding.

• Update RGB Mixer interactive: #1305

  • Show full value of colour in mixed colour.

  • Add parameter to show Pixelmania branding and force hexadecimal notation.

• Fix incorrect hexadecimal value in content.

• Dependency updates:

  • Update lxml from 4.5.1 to 4.5.2.

  • Update django-modeltranslation from 0.15 to 0.15.1.

  • Update sphinx from 3.1.1 to 3.1.2.

  • Update coverage from 5.1 to 5.2.1.

3.5.0

Release date: 7th July 2020

Changelog:

• Add ability to show colour codes in Hexadecimal on the Pixel Viewer interactive. #1277

• Add Hexadecimal version of colour mixer interactives. #1290

• Dependency updates:

  • Update Pillow from 7.1.2 to 7.2.0.

  • Update sphinx-rtd-theme from 0.4.3 to 0.5.0.

3.4.0

Release date: 1st July 2020

Changelog:

• Allow user to choose number of cards shown in the Binary Cards interactive, plus fit cards in groups of 8 on large screens. #1262 #1271

• Fix issues in LZSS Compression algorithm, expand its functionality, and replace space characters with the open box character for clarity. #1271 #1285

• Fix bug in JPEG Compression interactive where sometimes a checked checkbox was treated as unchecked and vice versa. #1269

• Prevent visual overflow of matrices in Matrix Simplifier interactive. #1138

• Replace downloadable Python programs for searching and sorting with links to updated Python programs on repl.it. #1279

• Dependency updates:

  • Update coverage from 5.0 to 5.1.

  • Update django-debug-toolbar from 2.1 to 2.2.

  • Update django-modeltranslation from 0.14.1 to 0.15.

  • Update django-statici18n from 1.8.3 to 1.9.0.

  • Update django-widget-tweaks from 1.4.5 to 1.4.8.

  • Update flake8 from 3.7.9 to 3.8.3.

  • Update lxml from 4.4.2 to 4.5.1.

  • Update Pillow from 7.1.1 to 7.1.2.

  • Update pydocstyle from 5.0.1 to 5.0.2.

  • Update sphinx from 2.3.0 to 3.1.1.

  • Update wheel from 0.33.6 to 0.34.2.

3.3.1

Release date: 22nd April 2020

Changelog:

• Solved bug in pixel viewer that was affecting some users. #1254

• Dependency updates:

  • Update Pillow from 6.2.1 to 7.1.1.

  • Update PyYAML from 5.2 to 5.3.1.

3.3.0

Release date: 26th December 2019

Summary of changes:

This release adds a new chapter on ‘Big Data’, various improvements for interactives, and updated project and chapter icons. A configuration tool for the sorting boxes interactive has been added, allowing teachers to setup specific examples for testing.

Changelog:

• Add new chapter: Big Data.

• Update project icon.

• Update chapter icons to better reflect their topics.

• Update rendering of some mathemetical equations.

• Add missing glossary terms. #1017

• Add ability for resulting equation in matrix-simplifier to be copied and pasted into all versions of the scene-editor interactive. #1168

• Add ability to remove all equations in the matrix-simplifier interactive at once. #1168

• Fix spelling in title of regular expression search interactive. #1172

• Update layout, simplify difficult password, and hide plaintext passwords of password guesser interactive. #1172

• Improve sorting boxes interactive with clearer feedback and configurator for teachers. #1196

• Update number memory interactive to reuse shorter password if the user remembers the longer one. #1172

• Fix bug in colour matcher where some bits did not flip when clicked on. #1167

• Set some external links to open in a new tab. #1175

• Update sentence about mesh points in computer graphics chapter. #1170

• Remove deprecated Google App Engine health check logic. #1187

• Remove use of float-left and float-right Bootstrap mixins. #1171

• Minor typo and grammar fixes.

• Dependency updates:

  • Update coverage from 4.5.4 to 5.0.

  • Update django-debug-toolbar from 2.0 to 2.1.

  • Update django-modeltranslation from 0.13.3 to 0.14.1.

  • Update flake8 from 3.7.8 to 3.7.9.

  • Update lxml from 4.4.1 to 4.4.2.

  • Update Pillow from 6.2.0 to 6.2.1.

  • Update pydocstyle from 4.0.1 to 5.0.1.

  • Update PyYAML from 5.1.2 to 5.2.

  • Update sphinx from 2.2.0 to 2.3.0.

3.2.0

Release date: 16th October 2019

Changelog:

• Rebuild scene editor interactive. #1115

• Create password guessing interactive. #606

• Add the ability to edit existing equations in matrix simplifier interactive. #1137

• Fix print preview to have ability to print more than just one page in Chrome. #1110

• Add glossary entries for the Computer Vision, Formal Languages and Network Communication Protocols chapters. #1017

• Enable subtitles in chapter introduction videos. #1089

• Exclude licences directory from Linkie. #1153

• Update Django from 1.11.16 to 2.2.3. #1111

3.1.0

Release date: 7th October 2019

Changelog:

• Rebuild AI sticks game. #574

• Rewrite RSA interactives. #1119

• Add note to users about broken interactives. #1152

• Content fixes and add glossary entries for the Computer Graphics and Complexity and Tractability chapters. #1017

• Amend content licence to exclude certain properties we don’t own. #1149

• Update versioning system description to reflect its use in practice. #1143

• Dependency updates:

  • Update pillow from 6.1.0 to 6.2.0.

3.0.5

Release date: 6th September 2019

Changelog:

• Fix broken URLs. #1141

3.0.4

Release date: 5th September 2019

Changelog:

• Rebuild matrix simplifier interactive. #375

• Fix URL parameters in searching boxes interactive. #1129

• Improvements to regular expression filter interactive. #1020

• Content fixes and add glossary entries for coding, data representation and HCI chapters. #1017

• Add glossary entries for AI chapter. #1136

• Improve list of contributors. #1127

• Dependency updates:

  • Update lxml from 4.3.4 to 4.4.1.

  • Update coverage from 4.5.3 to 4.5.4.

  • Update pyyaml from 5.1.1 to 5.1.2.

  • Update cssselect from 1.0.3 to 1.1.0.

  • Update pydocstyle from 4.0.0 to 4.0.1.

  • Update wheel from 0.33.4 to 0.33.6.

  • Update sphinx from 2.1.2 to 2.2.0.

3.0.3

Release date: 24th July 2019

Changelog:

• Fix bug where navbar mobile menu is positioned incorrectly. #1068

• Add link to the release archive in footer. #1098

• Remove references to Picasa. #1099

• Replace brackets with UTF-8 equivalent in archive links. #1093

• Update Google Cloud Platform health checks. #1105

• Dependency updates:

  • Update flake8 from 3.7.7 to 3.7.8.

  • Update pydocstyle from 3.0.0 to 4.0.0.

  • Update django-modeltranslation from 0.13.2 to 0.13.3.

3.0.2

Release date: 18th July 2019

Changelog:

• Add interactive to demonstrate limitations of short term memory. #144

• Add second short term memory interactive. #1090

• Fix broken links to old interactives in the computer graphics chapter.

• Update about page and introduction chapter. #1082

• Improve consistency in chapter section beginnings. #1065

• Align and resize homepage logos. #1050

• Center homepage icons on Firefox mobile. #1066

• Add link to Vox video on how snapchat filters work in the computer vision chapter. #367

• Reduce length of search bar on mobile. #1080

• Dependency updates:

  • Update django-modeltranslation from 0.13.1 to 0.13.2.

  • Update Pillow from 6.0.0 to 6.1.0.

  • Update python-bidi from 0.4.0 to 0.4.2.

3.0.1

Release date: 3rd July 2019

Changelog:

• Fix bug where binary cards were not flipping back to white on Chrome. #1056

• Add background to navigation dropdown on mobile. #1054

• Add option to reshuffle weights in sorting algorithms interactive. #1070

• Add link to curriculum guides in useful links. #1052

• Fix several content errors. #1044

  • Remove broken links that have no replacement link.

  • Improve formatting and correct spelling errors.

  • Correct sentence that states there are 0.6 kilometers in a mile.

• Fix formatting issues, add glossary links and a glossary term for bozo search. #1060

• Floating elements no longer overlap the subsection divider. #1059

• Add a redirect for the old homepage URL to the new homepage URL. #1058

• Correct spelling and formatting in the changelog. #1037

• Add a temporary fix for deploying static files. #1046

3.0.0

Release date: 30th June 2019

Changelog:

• Rebuild the Computer Science Field Guide website to use an open source Django system based off CS Unplugged (see the GitHub milestone). Major features include:

  • Greatly improved translation features.

  • Allowing student and teacher pages to use the same URLs (switch between modes available in page footer).

  • Search functionality for English chapters.

• Improve chapter content:

  • Chapter sections are now split across pages for better readability.

  • General content, grammar, and spelling fixes.

  • View glossary definitions within a page.

• Introduce new chapter sections:

  • ‘User experience’ by Hayley van Waas for the Human Computer Interaction chapter.

  • ‘General purpose compression’ by Hayley van Waas for the Coding - Compression chapter.

• Improve interactives:

  • Introduce automated thumbnail generator.

  • Introduce many ‘uninteractives’ - allowing image text to be translated.

  • Update existing interactives for better accessibility.

• Introduce new interactives:

  • Algorithm Timer

  • Braille Alphabet

  • City Trip

  • Dictionary Compression

  • Dot combinations

  • LZSS compression

  • LZW Compression

  • Pixel Grid

• Remove obsolete interactives:

  • MD5-hash

  • ncea-guide-selector

  • ziv-lempel-coding

• Redesign homepage.

• Update documentation and contributing guides.

• Update contributors page.

• Improve licencing structure to make it easier to find and navigate on GitHub.

• Rename ‘2D Arrow Manipulations’ interactive to ‘2D Shape Manipulations’.

• Introduce initial German and Spanish translations.

2.12.2

Release date: 5th June 2018

Changelog:

• Add optional parameters to Pixel Viewer interactive to specific starting image, hide pixel fill, and hide menu. #630

• Grammar/spelling fixes for Data Representation and Compression Coding chapters. #626

2.12.1

Release date: 7th March 2018

Changelog:

• Update Artificial Intelligence chapter to use shorter introduction video.

• Update Unicode Binary interactive to display UTF mode.

• Bugfixes for Sorting/Searching Boxes interactives.

• Grammar/spelling fixes for HCI chapter.

• Correct quote by Mike Fellows in Introduction chapter.

2.12.0

Release date: 13th February 2018

Changelog:

• Add Huffman coding section to compression chapter with Huffman Tree generator interactive.

• Add Viola-Jones face detection interactive.

• Add 2018 NCEA curriculum guides.

• Update Pixel Viewer interactive with threshold, blur, and edge detection modes for computer vision chapter. #32 #388

• Fix bug in Base Calculator interactive where computed value displayed incorrectly. #558

• Update Microsoft logo. #527

• Add videos to Formal Languages chapter #518

• Fix capitalisation of title of complexity and tractability chapter. #513

• Migrate Mathjax to new CDN. #482

2.11.0

Release date: 18th October 2017

Changelog:

• Add Bin Packing interactive. #490

• Correct Two’s Complement text. #503

• Remove contributor names from changelogs.

• Update JPEG interactive. #488

• Remove search as it focuses on outdated releases. #508

• Correctly detect text size for Unicode Length interactive. #501

• Fix broken link to CSFG in Network Protocols chapter. #504

• Fix typo in section 2.1.3. #507

2.10.1

Release date: 3rd September 2017

Changelog:

• Fix broken links to NCEA curriculum guides. #483

• Fix broken link to research paper. #484

• Fix panels showing ‘None’ as title. #485

2.10.0

Release date: 2nd September 2017

Notable changes:

This release adds a JPEG compression interactive, along with many bug fixes, and corrections.

The version numbering scheme now does not start with the v character (so v2.9.1 is 2.9.1). This to make the numbering consistent with our other projects (CS Unplugged and cs4teachers).

Changelog:

• Update Delay Analyser reset button to avoid accidental resets. #413

• Add video subtitle files.

• Clean up homepage for the NCEA Curriculum Guides. #358

• Replace cosine image. #73

• Fix bug in detecting defined permissions of files. #73

• Add Google Analytic skit videos to HCI chapter. #247

• Fix Washing Machine interactive in Formal Languages chapter. #411

• Correct spelling of aesthetics and add glossary definition. #405

• Fix rendering of glossary definition headings.

• Fix PBM image data. #412

• Fix link error in HCI chapter. #410

• Add missing NCEA guides files. #472

• Fix link to private YouTube video on packets. #408

• Update binary-cards interactive to handle a higher number of cards. #407

• Add ability to hide pixel colours in pixel value interactive. #476

2.9.1

Release date: 20th February 2017

Notable changes:

This release fixes a bug in the Computer Graphics chapter where some links to the 2D Arrow Manipulation interactives were broken due to an incorrect regex.

Changelog:

• Adam Gotlib #404

2.9.0

Release date: 27th January 2017

Notable changes:

This release adds an introductory video for the Complexity and Tractability chapter, updated text for Graphics Transformations section of the Computer Graphics chapter, as well as updated versions of the 2D Arrow Manipulation and FSA interactives.

Changelog:

• Add introductory video to Complexity and Tractability chapter.

• Rewrite Graphics Transformations section of Computer Graphics chapter. #402

• Rewrite 2D Arrow Manipulation interactives. #372 #373

• Add list of authors in the sidebar of chapter page. #396

• Update FSA interactives. #45 #46 #47 #48

• Add NFA guesser interactive.

• Update APCSP framework. #399

2.8.1

Release date: 21st October 2016

Changelog:

• Update introduction chapter. #231

• Add notice of changes to AP-CSP curriculum in Fall 2016 release.

• Skip parsing # characters at start of Markdown links.

2.8.0

Release date: 19th October 2016

Notable changes:

This release adds an introductory video for the Human Computer Interaction chapter, plus a draft of guides for mapping the Computer Science Field Guide to the AP CSP curriculum.

Changelog:

• Add introductory video to Human Computer Interaction chapter.

• Add draft of guides for the AP CSP curriculum. #316

• Update and fix issues in high-score-boxes interactive. #390 #391 #393

• Add subtraction command to mips-simulator interactive. The interactive can now handle subtraction down to zero. #382

• Update sponsor information in footer.

• Improve the visibilty of warning panels. #389

• Fix positioning of table of contents sidebar. #387

• Fix typos in Formal Languages chapter. #385

• Update 404 page to avoid updating after each release. #394

• Remove duplicate introduction to teacher guide. #213

• Add link to article on representing a 1 bit image. #376

• Fix broken link to contributors page in footer. #383

• Replace broken link to Eliza chatterbot. #384

• Fix footer link colour in teacher version. #395

2.7.1

Release date: 5th September 2016

Notable changes:

• Fixed broken link in footer to contributors page.

A full list of changes in this version is available on GitHub

2.7.0

Release date: 23rd August 2016

Notable changes:

New video: Formal Languages now has an introductory video. New interactive: The [hexadecimal background colour interactive interactives/hex-background-colour/index.html) allows a user to change the background colour of the page. New curriculum guide: A guide for NCEA Artificial Intelligence: Turing Test has been added. Updated interactives: The box translation and box rotation interactives are now open source and have been given a new look and made mobile friendly. Generation improvements: Basic translation support. Settings are now specific to each language, and contain the translation text. Website improvements: Added help guide for WebGL interactives. - Also includes bug fixes to interactives, new links to supporting videos, and various text corrections from our staff and contributors.

A full list of changes in this version is available on GitHub

2.6.1

Release date: 14th July 2016

Notable changes:

• Fixed issue on Human Computer Interaction chapter where duplicate library was causing several UI elements to not behave correctly.

2.6.0

Release date: 16th June 2016

Notable changes:

New feature: PDF output - A downloadable PDF of both student and teacher versions is now available from the homepage. The PDF also functions well as an ebook, with functional links to headings, glossary entries, interactives, and online resources. New feature: Printer friendly webpages - When printing a page of the CSFG through a browser, the page displays in a printer friendly manner by hiding navigational panels, opening all panels, and providing extra links to online resources. New interactive: The binary cards interactive emulates the Binary Cards CS Unplugged activity, used to teach binary numbers. New interactive: The high score boxes interactive was developed to give an example of searching boxes to find a maximum value to the student. New interactive: The action menu interactive is a small dropdown menu with one option that has severe consequences, but no confirmation screen if the user selects that option (used to demonstrate a key HCI concept). Updated interactive: The trainsylvania interactive (and supporting images/files) have been given a fresh coat of colour and a new station name. Updated interactive: The trainsylvania planner is used alongside the trainsylvania interactive, and allows the user to input a path of train trips to see the resulting destination. Updated interactive: The base calculator allows a student to calculate a number, using a specific number base (binary, hexadecimal, etc). Updated interactive: The big number calculator allows a student to perform calculations with very large numbers/results. Website improvements: Redesigned homepage and footer with useful links and a splash of colour. Math equations are now line wrapped, and MathJax is loaded from a CDN. Images can now have text wrapped around them on a page. Generation improvements: Improvements to internal link creation (glossary links in particular). Separated dependency installation from generation script (see documentation for how to install and run generation script). Project improvements: Added documentation for contributing to and developing this project, including a code of conduct.

A full list of changes in this version is available on GitHub

2.5.0

Release date: 13th May 2016

Notable changes:

• The Data Representation chapter has been rewritten and reorganised to be easier to follow, and three NCEA assessment guides have been written for students aiming for merit/excellence:

• Numbers (Two’s Complement)

• Text (Unicode)

• Colours (Various bit depths)

The chapter and assessment guides have been rewritten to take account of new feedback from the marking process and our own observations of student work.

As part of the rewrite of the Data Representation chapter, the following interactives were developed:

• New interactive: The unicode binary displays the binary for a given character (or character by decimal number) dynamically with different encodings.

• New interactive: The unicode character displays the character for a given decimal value.

• New interactive: The unicode length displays the length (in bits) of text encoded using different encodings.

• Updated interactive: The colour matcher has been redesigned to display values in binary, plus allow students to see and edit the bit values. The interface has also been restructured for readability and ease of use.

The old version of the Data Representation chapter can be found here

• Website improvements: A new image previewer was implemented, along with bugfixes to iFrame and panel rendering.

• Generation improvements: The Markdown parser has been replaced due to existing parsing issues. The new parser also gives us a large performance boost. A text box tag has also been added to highlight important text.

A full list of changes in this version is available on GitHub

2.4.1

Release date: 29th April 2016

Notable changes:

• Fixed version numbering system to allow hotfix changes

A full list of changes in this version is available on GitHub

2.4

Release date: 29th April 2016

Notable changes:

• Large number of typo, grammar, link, and math syntax fixes and also content corrections by contributors.

• New interactive: Added GTIN-13 checksum calculator interactive for calculating the last digit for a GTIN-13 barcode.

• Updated interactive: The regular expression search interactive has been updated and added to the repository.

• Updated interactive: The image bit comparer interactive has been updated and added to the repository. It also has a changing bits mode which allows the user to modify the number of bits for storing each colour.

• Added XKCD mouseover text (similar behaviour to website).

• Added feedback modal to allow developers to directly post issues to GitHub.

• Added encoding for HTML entities to stop certain characters not appearing correctly in browsers.

• Added summary of output at end of generation script.

• Added message for developers to contribute in the web console.

A full list of changes in this version is available on GitHub

2.3

Release date: 10th March 2016

Notable changes:

• Readability improvements to text within many chapters (grammer issues/typos) and to the Python scripts within the Algorithms chapter.

• Updated interactive: The RSA encryption and decryption interactives within Encryption have been updated and added to the repository.

• Updated interactive: The searching algorithms interactive within Algorithms have been updated and added to the repository.

• Updated interactive: The word filter interactive within Formal Languages have been updated and added to the repository.

• Updated interactives: Both the MIPS assembler and MIPS simulator were made open source by the original author, and we were given permission to incorporate our repository, and have been added to Programming Languages.

• A list of all interactives are now available on the interactives page

A full list of changes in this version is available on GitHub

2.2

Release date: 19th February 2016

Notable changes:

• New interactive: Parity trick with separate modes for practicing setting parity, practicing detecting parity, and the whole trick. Also has a sandbox mode.

• Updated interactives: Two colour mixers, one for RGB and one for CMY have been added.

• Updated interactive: A colour matcher interactive has been added for matching a colour in both 24 bit and 8 bit.

• Updated interactive: A python interpreter interactive has been added for the programming languages chapter.

• Website improvements: Code blocks now have syntax highlighting when a language is specified, dropdown arrows are fixed in Mozilla Firefox browsers, and whole page interactives now have nicer link buttons.

A full list of changes in this version is available on GitHub

2.1

Release date: 12th February 2016

Notable changes:

• Fixed many broken links and typos from 2.0.0

• Added calculator interactives to Introduction

• Added RSA key generator to Encryption

• Rewritten Braille Section in Data Representation

A full list of changes in this version is available on GitHub

2.0

Release date: 5th February 2016

Notable changes:

• First open source release

• Produces both student and teacher versions

• Produces landing page for selecting language

• Added new NCEA curriculum guides on Encryption and Human Computer Interaction

A full list of changes in this version is available on GitHub

Comments:

The first major step in releasing a open source version of the Computer Science Field Guide. While some content (most notably interactives) have yet to be added to the new system, we are releasing this update for New Zealand teachers to use at the beginning of their academic year. For any interactives that are missing, links are in place to the older interactives.

2.0-alpha.3

Release date: 29th January 2016

2.0-alpha.2

Release date: 25th January 2016

2.0-alpha.1

Release date: 2nd December 2015

Comments: Released at CS4HS 2015.

1.?.?

Release date: 3rd February 2015

Comments:

The last version of the CSFG before the open source version was adopted.