Helper Commands for Developing

Note

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

The CS Unplugged 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 csu and can be found in the cs-unplugged 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):

$ ./csu [COMMAND]

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

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

Technical developers should also understand the dev command.

build

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

clean

Running ./csu clean deletes ‘dangling’ Docker images left over from builds, which will free up hard drive space.

dev

The ./csu dev [DEV_COMMAND] command runs developer tasks, where [DEV_COMMAND] is a word from the list below:

logs

Running ./csu 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.

flush

Running ./csu dev flush runs the Django flush command to flush the database.

makemigrations

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

makeresources

Running ./csu dev makeresources runs the custom Django makeresources command to create static resource PDF files.

migrate

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

rebuild_index

Running ./csu dev rebuild_index runs the Haystack rebuild_index Django command.

shell

Running ./csu dev shell opens a bash terminal within the Django container (this requires the CS Unplugged system to be running).

This is the equivalent to entering docker-compose run django bash.

static

Running ./csu 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.

static_prod

Running ./csu dev static_prod runs the commands for generating production static files for the website. This produces compressed SASS files without sourcemaps.

style

Running ./csu 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

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

test_backwards

Running ./csu 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 ./csu dev test_coverage will display a table detailing test code coverage, from the report generated by ./csu dev test.

test_specific

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

updatedata

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

end

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

help

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

restart

Running ./csu restart is a shortcut for running:

  • ./csu end
  • ./csu start

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

start

Running ./csu 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 ./csu 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 ./csu build). Once the images are built, the script will run these images in containers.

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

update

Running ./csu 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 localhost to view the website.

In more detail, ./csu 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.

wipe

Running ./csu wipe delete all Docker containers and images on your computer. Once this command has be run, a full download and rebuild of images is required to run the system (can be triggered by the build or start commands).

You now know the basic commands for using the CS Unplugged 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.