Updating forked dependencies - firedrakeproject/firedrake GitHub Wiki

Motivation

Firedrake maintains forks of some of its dependencies (e.g. PETSc). This is so we can control the release schedule and protect users from breaking upstream changes whilst also be able to use the latest versions of these projects if we require specific changes.

Process

These forked repositories should be updated every few months using the following steps:

Prerequisites

Have appropriate permissions to be able to push to the forked repository.
git clone a local copy of the forked repository.
Add the upstream repository as an extra git remote:
```
$ git remote add upstream <upstream URL>
```

Steps

Make sure that the right branch is checked out and up-to-date (we assume throughout that this branch is called firedrake):
```
$ git checkout firedrake
$ git pull
```
Update the upstream remote:
```
$ git fetch upstream
```
Update the local branch:
```
$ git merge upstream/main
```
Note that git merge should be used here instead of git rebase to avoid rewriting the commit history and breaking firedrake-update.

Create, checkout and push a new branch that is identical to the current one:

$ git checkout -b <github username>/upstream-update
$ git push -u origin <github username>/upstream-update

Create a pull request to the forked repository using this branch (example).
Check that the Firedrake test suite passes using this branch following these instructions.
Merge the pull request, updating the forked repository. You should also close the associated Firedrake pull request opened to run the test suite (see above).

Important

The SLEPc fork must be kept up to date with the PETSc fork. Specifically check that at a bare minimum the version specified in /include/petscversion.h matches /include/slepcversion.h.
When updating PETSc, users should be notified via a Slack announcement that this has been done as they may need to update an external PETSc installation manually.