Bridget

This repo contains the thrift definitions defining the API between native layers (iOS, Android) and Webview.

The repo is also responsible for generating and publishing packages to be used by iOS, Android and the Webview.

Thrift definitions

native.thrift are the functions to be implemented by iOS and Android. The webview will be able to call these functions with the specified arguments.

Generated packages

The Swift and TypeScript packages are generated and published using this GitHub action.

• The TypeScript package can be installed from NPM
• Swift package can be installed with Swift Package Manager from GitHub

For Android, Java interfaces for Bridget services are generated at build time in the Bridget module.

Adding a new function

1. Define the function in native.thrift if it needs to be implemented in Swift & Kotlin
2. Make sure to add a comment above the function to document what it does. It's a good idea to add the version it was available from too (this will be a minor update to the latest tag)
3. Make a pull request. It would be good to get a review from all teams who would need to implement or call the function. e.g. Android, iOS and apps-rendering
4. Merging into main will automatically run the GitHub actions to publish packages
5. If you don't see the published packages, start by inspecting the GitHub action started on the branch that was merged into main
6. Bump the version in your repo (iOS, Android or apps-rendering) and implement the function or make the function call. Make sure the function is always available in the current environment. This can be done by checking the thrift version number of the webView or native layer

Releasing Bridget

Bridget is released by the generate-packages.yml GitHub Action. The repository needs the following secrets available to the action:

• NPM_TOKEN
• ACCESS_TOKEN: a GitHub Personal Access Token (PAT). The PAT needs read/write permissions for the guardian/bridget-swift repository. Please use a Fine Grained PAT.

Testing a prerelease

You can use prereleases to test a new version of the models across web, Android and iOS without making a full release.

To do this, create a new prerelease in the GitHub releases UI (or click here). The tag is used as the version. For example, once the prerelease action has finished running for a prerelease created with tag v0.0.0-2024-02-16:

• install from npm: npm install @guardian/[email protected]
• find the swift package: https://github.com/guardian/bridget-swift/tree/v0.0.0-2024-02-16
• find the android package: https://github.com/guardian/bridget-android/tree/v0.0.0-2024-02-16

GitHub Action generate-swift-package fails with "Authentication failed"

This is likely caused by an expired ACCESS_TOKEN repository secret. To fix this, you should update the ACCESS_TOKEN secret with a new Fine Grained PAT as described in Releasing Bridget. Note: updating a secret requires admin permissions on the repository.

Setting the version bump

Versions are managed by github-tag-action. The default bump is a minor version. However, you can specify what version bump to perform using a known symbol at the end of your merge commit message.

For example, to perform a patch bump, your merge commit message could look like:

Release new version of Bridget. #patch

You can use the following symbols:

• #patch
• #minor
• #major
• #none, which will not perform a version bump

For more information, see the github-tag-action docs.

About the name

The name Bridget was chosen out of a list of a dozen suggestions, containing mostly bridge related puns.