Auto-updating packages

Auto-updating packages#

When building your book, you are making use of various Python packages: the teachbooks and jupyter-book packages themselves, but also packages for extensions. These are regularly updated, however, those updates are not necessarily incorporated into your book automatically. The list of packages and their versions are defined in the requirements.txt file, which is provided as part of the template. Consider the following three options for how packages can be specified:

  1. requirements.txt only contains names of packages like: download_link_replacer. In that case, your deploy-book-workflow will take the most up-to-date version when making your book website once a week (as the chache will be cleared once a week). This might lead to unexpected changes when a new version has been released (although new versions will generally be backwards compatible).

  2. requirements.txt contains names of packages with a specified version like: download_link_replacer==1.0.4. In that case, your deploy-book-workflow always uses that specific version. In doing so, you’ll never get a new update unless you explicitly adapt the version in requirements.txt. If you’d like to get notified for updates, you might consider using GitHub’s Dependabot.

  3. A combination of 1. and 2.: In that case (once a week at most) you will receive new versions for only the unfixed packages, no updates for the fixed versions.

For the case of specified versions, you can use GitHub’s Dependabot to notify you that a new version is available and to automatically set up a Pull Request to update your book with the new version.

Notifications updated packages with Dependabot#

Dependabot checks the specified version of packages in your requirements.txt file and, if a new version is found, will create a new branch, update the requirements.txt file and open a Pull Request whenever there’s an update available for that package. Note that packages without a fixed version are ignored by Dependabot.

To activate this feature:

  1. Specify version for all packages you want to be notified on in your requirements.txt file. See requirements.txt of this manual as an example

  2. In the .github/ directory, add a file named dependabot.yml with the following content (note that sphinx-thebe (used in python live coding) and docutils (using in APA referencing) are ignored because these require a very specific version to work):

version: 2
updates:
  - package-ecosystem: "pip" 
    directory: "/"
    schedule:
      interval: "weekly"
      day: "sunday"
      time: "22:59"
    ignore:
      - dependency-name: "sphinx-thebe"
      - dependency-name: "docutils"

This check will run every Sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:

  1. A new branch is created with a name that begins with dependabot... in the repository

  2. A commit is made updating requirements.txt (e.g., jupyterbook_patches==1.4.2 is changed to jupyterbook_patches==1.4.4)

  3. A pull request will be created to merge the new branch into the default branch. This pull request must be manually reviewed and merged. Afterwards the dependabot branch can be deleted (automatically).

Note that these activities will occur automatically and may trigger other workflows in your repository (for example, the building of a book on another branch). If the workflow call-deploy-book is used, and you don’t want the dependabot branches to be built and deployed (and all other branches you do want), you can achieve this by adding the following text to the file call-deploy-book.yml:

on:
  push:
    branches:
    - '**'
    - '!dependabot**'

If you want another scheduled workflow, see Dependabot options reference for the options.

If you want to manually trigger the Dependabot workflow, you can do this by doing the next steps:

  1. Go to your repository on Github.

  2. Choose Insights.

  3. Choose Dependency graph.

  4. Choose Dependabot.

  5. Choose Recent update jobs next to pip requirements.txt.

  6. Choose Check for updates.

Contents