admin2/manual_teachbooks
1
0
Fork 0
mirror of https://github.com/TeachBooks/manual.git synced 2026-11-12 22:35:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

update updated_env text for clarity

Browse source
This commit is contained in:
Robert Lanzafame 2025-04-02 06:14:24 +02:00 • committed by GitHub
parent 89fe14cc34
commit 6d3e647a94
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 12 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

20
book/features/update_env.md
View file

@ -9,18 +9,21 @@ This page is useful for user type 4-5.
# Auto-updating packages
When building your book, your making use of packages: the teachbooks and jupyterbook packages themselves, but also packages for extensions. These are regularly updated, while those updates are not necessarily taken into your book. This is all defined in the `requirements.txt` file, which is provided as part of the [template](../external/template/README.md). There are three options:
1. `requirements.txt` only contains names of packages like: `download_link_replacer`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) 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 new version come out, although new version are in general backwards compatible.
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](../external/template/README.md). 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](../external/deploy-book-workflow/README.md) 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).
1. `requirements.txt` contains names of packages with a specified version like: `download_link_replacer==1.0.4`. In that case, your [deploy-book-workflow](../external/deploy-book-workflow/README.md) 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.
1. 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. In this case you can also use GitHub's Dependabot.
1. 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 opens a branch and pull requests whenever there's an update available for that package. Note that package without a fixed version are ignored by 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`](https://github.com/TeachBooks/manual/blob/release/requirements.txt) of this manual as an example
1. In the `.github/` directory, add a file named `dependabot.yml` with the following content (note that sphinx-thebe (used in [python live coding](./live_code.ipynb)) and docutils (using in [APA referencing](./apa.md)) are ignored because these require a very specific version to work):
```yaml
version: 2
updates:
@ -35,11 +38,12 @@ updates:
- dependency-name: "docutils"
```
This will check every sunday around midnight (UTC) whether any of the fixed-version packages are updated. If so, several things will happen:
1. A new branch starting with _dependabot_ will be created in the repository and any relevant workflows will be triggered.
1. A _pull request_ will be created to pull the new branch into the _default_ branch. This pull request must be manually reviewed and merged. Afterwards the _dependabot_ branch can be deleted (automatically).
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
1. A commit is made updating `requirements.txt` (e.g., `jupyterbook_patches==1.4.2` is changed to `jupyterbook_patches==1.4.4`)
1. 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).
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 next to the file `call-deploy-book.yml`:
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`:
```yaml
on: