From 20cf47abe6ffd9ddf1464ffc58e46c2603b7c5a6 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 17 Jan 2025 11:01:33 +0100 Subject: [PATCH 1/3] First proposal --- book/_toc.yml | 1 + book/features/update_env.md | 51 +++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+) create mode 100644 book/features/update_env.md diff --git a/book/_toc.yml b/book/_toc.yml index 89eb15e..6bfc2de 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -55,6 +55,7 @@ parts: - file: external/deploy-book-workflow/README.md - file: features/local_server - file: external/Nested-Books/README.md + - file: features/update_env - file: features/sphinx_extensions.md sections: - file: external/Download-Link-Replacer/README.md diff --git a/book/features/update_env.md b/book/features/update_env.md new file mode 100644 index 0000000..8a58cc0 --- /dev/null +++ b/book/features/update_env.md @@ -0,0 +1,51 @@ +# Auto-updating packages + +{bdg-dark}`Git Workflow` + +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 two options: +- `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 every week when making your book website. This might lead to unexpected changes when new version come out, although new version are in general backwards compatible. +- `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 + +## Notifications updated packages with Dependabot + +Dependabot checks the version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available. To activate this feature: +- 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 +- 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: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + day: "sunday" + time: "22:59" + ignore: + - dependency-name: "sphinx-thebe" + - dependency-name: "docutils" +``` + +This will check every sunday around midnight (UTC) whether any of the 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. + +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`: + +```yaml +on: + push: + branches: + - '**' + - '!dependabot**' +``` + +If you want another scheduled workflow, see [Dependabot options reference](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#schedule-) 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](https://github.com/). +1. Choose **Insights**. +1. Choose **Dependency graph**. +1. Choose **Dependabot**. +1. Choose **Recent update jobs** next to pip `requirements.txt`. +1. Choose **Check for updates**. \ No newline at end of file From 310af99a96efa6975c9f02dae547163e7eadcbf7 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 17 Jan 2025 11:28:01 +0100 Subject: [PATCH 2/3] - to 1. 2. --- book/features/update_env.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/update_env.md b/book/features/update_env.md index 8a58cc0..b63f067 100644 --- a/book/features/update_env.md +++ b/book/features/update_env.md @@ -9,8 +9,8 @@ When building your book, your making use of packages: the teachbooks and jupyter ## Notifications updated packages with Dependabot Dependabot checks the version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available. To activate this feature: -- 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 -- 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): +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: From e43867a924d4b4e81abf9a48398e7939ed377351 Mon Sep 17 00:00:00 2001 From: Dennis den Ouden-van der Horst <49307154+douden@users.noreply.github.com> Date: Fri, 17 Jan 2025 13:49:13 +0100 Subject: [PATCH 3/3] Update update_env.md --- book/features/update_env.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/book/features/update_env.md b/book/features/update_env.md index b63f067..ad4096b 100644 --- a/book/features/update_env.md +++ b/book/features/update_env.md @@ -2,13 +2,16 @@ {bdg-dark}`Git Workflow` -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 two options: -- `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 every week when making your book website. This might lead to unexpected changes when new version come out, although new version are in general backwards compatible. -- `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 +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. +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. ## Notifications updated packages with Dependabot -Dependabot checks the version of packages in your `requirements.txt` file and opens a branch and pull requests whenever there's an update available. To activate this feature: +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. + +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 @@ -25,9 +28,9 @@ updates: - dependency-name: "docutils" ``` -This will check every sunday around midnight (UTC) whether any of the packages are updated. If so, several things will happen: +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. +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). 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`: @@ -48,4 +51,4 @@ If you want to manually trigger the Dependabot workflow, you can do this by doin 1. Choose **Dependency graph**. 1. Choose **Dependabot**. 1. Choose **Recent update jobs** next to pip `requirements.txt`. -1. Choose **Check for updates**. \ No newline at end of file +1. Choose **Check for updates**.