From 7482c69a69a1e8502b9085d3f43d1c8036351a8f Mon Sep 17 00:00:00 2001 From: John Boyes Date: Wed, 12 Aug 2020 11:27:50 +0700 Subject: [PATCH] Document dependency management in CONTRIBUTING.md (#33) --- CONTRIBUTING.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55abf15..90614a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,3 +25,29 @@ The [tests](.github/workflows/tests.yml) are [end-to-end black box tests](http:/ There is no need for a separate language for the tests - as we are running the actual GitHub Action we are able to use the [GitHub Action workflow syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions), which gives us what we need (e.g. [expressions](https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#about-contexts-and-expressions)) to write clean tests. +## Updating dependencies + +We use [GitHub Dependabot](https://docs.github.com/en/github/administering-a-repository/keeping-your-dependencies-updated-automatically) +([bought by GitHub in 2019](https://dependabot.com/blog/hello-github/) and now +[baked into GitHub](https://github.blog/2020-06-01-keep-all-your-packages-up-to-date-with-dependabot/)) +to manage our dependencies. + +Whenever possible, we let Dependabot update our dependencies automatically (by +[automatically creating a PR](https://docs.github.com/en/github/administering-a-repository/managing-pull-requests-for-dependency-updates#about-github-dependabot-pull-requests) +for us to merge). + +Dependabot will +[automatically update non-Docker dependencies in our GitHub Actions](https://github.blog/2020-06-25-dependabot-now-updates-your-actions-workflows/). + +For our other dependencies which cannot be updated automatically by Dependabot, we employ a bit of a hack. +We have a [`dependabot_hack.yml`](.github/workflows/dependabot_hack.yml) GitHub Action which triggers a Dependabot PR when these other dependencies have a new version to update to. This GitHub Action is set to never actually run; it exists just so that Dependabot can do its thing. The `dependabot_hack.yml` documents where in our codebase that we then need to **update to the new version manually** (we then **add this manual update as another commit to the PR that Dependabot creates**). NB we are able to use this hack to **manage _any_ dependency that uses +[GitHub releases](https://docs.github.com/en/github/administering-a-repository/about-releases)** - we are not limited to just dependencies which are themselves GitHub Actions (this is because Dependabot doesn't care +whether the dependencies are valid GitHub Actions, it just parses the file and updates any versions that are +managed through GitHub releases). + +We could in theory automate this entirely (by e.g. having a GitHub Action that is triggered by Dependabot PRs, +which updates the version in the requisite files and then adds the change in a new commit to the Dependabot PR), +but that would be overkill for now. + +Eventually as Dependabot adds more features we may be able to remove this workaround. +