With the merge of PR#149, we turned on continuous integration (CI) for the book. This means that, everytime we commit something to the main branch of the book repository, a little robot at Github sets up a full environment and runs the book entirely to ensure all the code runs without glitches. This is common practice in modern software engineering, and we are excited about adopting it for book writing.

Besides providing an additional check to make sure we keep our book up to date and working as expected, the adoption of CI implies one step further in the philosophy we are trying to live by in this project. We have long been of the opinion that, for Geographic Data Science, code represents a medium of comunication and a vehicle for teaching. Code is (almost) like text when it comes to teaching computational concepts. By adopting CI for the book open repository, we’re also implying the oposite (text as code) also holds true: we treat the book as an artifact that contains software and that, as such, we believe needs to follow similar practices.

If you want to check how the last run went, click on the badge:

Test Book

We should also mention the “tester” is the second, not the first, robot we welcome to the GDS Book family. For a long(er) time, we have had a different one that automatically re-builds the website that hosts the book whenever we make a new change. For the list of builds of this bot, click on the badge below:

Build Jupyter book

Tech epilogue

If you are interested in the backend and various wirings we do to create and operate both bots, here’s a short overview.

We use Github Actions, which allows us to trigger actions on every commit. We have two of these “actions” specified, one for the test bot, one for the build bot. The specs of each are specified on a separate .yml file that lives under the gdsbook/.gihub/workflows directory of the book repository.

To test the book on Windows/Linux/macOS, we set up a conda environment that mirrors the GDS env (6.0post1 at the time of writing, but we plan to keep this in sync with the latest version), and the use make test, a comand that uses the Makefile in the repository, to execute every chapter in the book. This is a lightweight approach that allows us to use the same workflow when we’re testing the book locally on our own machines and when it runs on Github’s cloud.

The infrastructure to build the website is a bit more lightweight in that we only really need jupyterbook and affiliated dependencies to be able to create an updated version of the website from the notebook files. We use a small .yml file to set up such environment.