When dependencies release new versions, we want to make sure they don't break Relay when we upgrade. This document describes what to look for when an upgrade comes in.
Typically, we receive update notifications from Dependabot, which periodically checks for new versions of dependencies, and then submits pull requests to update them. Project members can view the details of the latest dependency scans to troubleshoot issues.
Some terms to be aware of:
- Checks: at the bottom of a Pull Request's page, GitHub will list the outcomes of Continuous Integration runs. It calls these "checks".
- CI results: to view the results of a CI run (e.g.
test_frontend), click the "Details" link next to the respective Check. - Preview deployment: for
every PR, a copy of the frontend with that PR's code is deployed to Netlify. You
can view that deployment by clicking the "Details" link next to the
netlify/fx-relay-demo/deploy-previewCheck.
All dependency updates involve verifying that all Checks are successful, investigating the results of failing CI runs, and a cursory inspection of the changelog (if any) for anything that might be relevant to Relay, in particular if a dependency's major version is bumped, or if a dependency doesn't use Semantic Versioning.
If you're unsure whether anything looks as expected, try to replicate what
you're doing on the main branch. If the results differ, there's probably an
issue with the update.
Make sure to do a fresh install of the dependencies when switching branches!
You can line up multiple Dependabot PRs for merging by using the "Merge when ready"
button to add to the merge queue. The suggested comment @dependabot merge
does not work with the merge queue, and will not merge the PR.
Alternatively, you can use the CLI tool pmac
to manually group updates into a single PR.
We have two npm projects in this repository: the website frontend (identified by
/frontend/package.json), and the root project from which our end-to-end tests
are run (identified by /package.json). The former is defined as a
workspace in the latter,
and both have their dependencies checked by Dependabot.
What follows is a list of dependencies and how to check for potential breakage when they release new versions:
For linters, type definitions, and non-Playwright testing-related packages, a
successful CI run generally provides enough confidence that the upgrade is fine.
That said, it can't harm to occassionally scan the results of the
build_frontend or test_frontend CI runs to see if any new warnings were
added. If jest-junit is updated, you'll want to check that CircleCI can still
see code coverage for the frontend.
Our Playwright tests run as a GitHub action Relay e2e Tests once a day from
the main branch. See ../e2e-tests/README.md
for instructions on running the tests locally.
To test updates to @playwright/test and dotenv, add the following to the
.env file:
E2E_TEST_ACCOUNT_PASSWORD=<a_long_random_string_like_a_uuid>
E2E_TEST_ENV=stage
Check out the update branch and run:
npm install
npx playwright install
npx playwright test
This will confirm that dotenv picked up the settings from .env, and that
the new playwright runs against stage.
Once the PR is merged, you can wait for the daily test run, or manually run the
test by going to the Relay e2e Tests GitHub Action page, select "Run
workflow", and pick the main branch and the stage environment.
These dependencies handle most of the dynamic UI elements in our frontend, such as the user menu and the app menu in the header, the modals when claiming a subdomain or creating a new custom mask, or the toggle that allows you to set a mask to block nothing, promotional emails, or everything. To verfy these updates, open the preview deployments and check that you can still interact with those using both a keyboard and a mouse.
Fluent handles localisation, so verifying these involves setting your browser language to something other than English, and verifing that the website content indeed shows up in your chosen different language.
Next.js handles most of our frontend build pipeline and bundling the website. To spot-check this update, open the Preview deployment to verify that the website was put together successfully, and that you can navigate between different pages (e.g. from the home to the FAQ) without issues.
SWR is responsible for making requests to the backend, whereas MSW intercepts API calls in the preview deployment and returns mock data instead. Both can be verified by opening the preview deployment and making sure that you can still interact with the API (e.g. by creating a new mask).
Sass gives us some handy tooling to ease working with CSS, and Protocol is Mozilla's design system from which we use some Sass variables. Both can be verified by checking the preview deployment and making sure the styling doesn't look weird.
React is our front-end framework. If you can open the preview deployment and general interactions still work, these upgrades were probably successful.
Handles the toast notification when e.g. saving settings, so if you can see that in the preview deployment, it's still working as intended.
The most visible use of this is to make sure that the "Help & Tips" card in the bottom right-hand corner of the Relay website sticks to the bottom of the viewport, until the footer scrolls into view, in which case it should start scrolling up. If you can still see that behaviour in the preview deployment, it's probably fine.
Used to see how different parts of the website are being used via Google Analytics. If you do not have Do not track enabled in your browser, then you should see pings we send to GA being logged in the Console in the browser Dev Tools when browsing the preview deployment, e.g.
[react-ga] – "called ga('send', 'pageview', path);"
[react-ga] – "with path: /accounts/profile/?mockId=some"
Used for the list of countries in the "What country or region do you live in?"
dropdown at /premium/waitlist, so if you see that, it's all good.
Used to run basic code formatting when committing. You can verify that these
work locally by changing formatting (e.g. changing " into ') and checking
that it gets changed back (resulting in an empty commit) when committing.
To watch files when running npm run watch. You can verify that this still
works by running that command and making sure that the server restarts if you
edit a source file.
The Python requirements are in /requirements.txt at the project root. We
do not distinguish between development and production requirements for Python.
We recommend setting up and using a Python virtual environment, to keep Relay
packages distinct from other system packages - see the
Development setup instructions
for details.
The command python -m pip install -r requirements.txt will install the packages.
In general, Python library developers write release notes, even if Dependabot has trouble finding and linking to them. It is worth reading the release notes to determine the changes from the previous version, and take note of suggested changes to the Relay codebase.
Python developers often follow the Python version support schedule, dropping support for old Python versions even with few code changes. These are often released as minor version updates, occasionally as major updates, but are generally safe updates for Relay. The currently used Python version can be found in several places, such as the Development setup instructions. Relay engineers attempt to update to new Python versions within 12 months of their release.
What follows is a list of dependencies and how to check for potential breakage when they release new versions:
For linters, see the details of the black style check test step for any breaking
syntax changes. If this test step passes, the upgrade is probably OK, and any warnings
can be handled in later PRs.
For testing tools, a successful CI test run means the upgrade is probably OK, and any new warnings can be handled in later PRs.
For mypy and stub libraries, see the details of the mypy type check test step for any
breaking typing changes. If this test step passes, the upgrade is probably OK, and any
new warnings can be handled in later PRs.
This is the interface library for Amazon Web Services (AWS). This library is generated from the API definition files, and has multiple patch updates most weeks. A successful CI test run means the upgrade is OK.
See the changelog notes for a taste of the changes AWS developers are making to the services we use. We use clients for the following services in code:
- S3 - Simple Storage Service
- SES - Simple Email Service
- SQS - Simple Queue Service
We use these additional AWS services in the Relay system:
- CloudFront - Content delivery network
- IAM - Identity and Access Management
- KMS - Key Management Service
- Route53 - Domain Name Service
- SNS - Simple Notification Service
It's a good idea to search the changelog for any changes to these services between the current library version that Relay uses and the version in the dependency update PR.
Because the boto3 library and release notes are so large, you may have trouble reading them in the GitHub website UI. If so, you can view the raw changelog here: https://raw.githubusercontent.com/boto/boto3/develop/CHANGELOG.rst
Relay currently uses a Long Term Support (LTS) release of Django. See the Django download page for version details. Patch versions of the current version (such as 3.2.19 to 3.2.20) are often security updates, and the release notes should be read to determine the impact to Relay, as well as merged as soon as possible.
We try to update to the next LTS version within the year of release. This is often a multi-week process, requiring updates to several resources, and tracked in a GitHub issue and project task. Close dependency updates to the next LTS version if you are not ready to update, to get them out of the PR queue.
We skip non-LTS versions (such as 5.0.0 and 5.1.0). Use the comment
@dependabot ignore this minor version to close the PR and avoid new updates for
that series.
This package is development-only, and updates are generally safe to merge. To test,
update the package, start the server, and load /emails/wrapped_email_test locally.
The toolbar will be on the right side of the page, either expanded or minimized as
"DjDT" in the upper right corner.