diff --git a/shorebird_code_push/CHANGELOG.md b/shorebird_code_push/CHANGELOG.md index 483c20b..3468abe 100644 --- a/shorebird_code_push/CHANGELOG.md +++ b/shorebird_code_push/CHANGELOG.md @@ -1,3 +1,8 @@ +# 1.0.0 + +- Change `downloadUpdate` to `downloadUpdateIfAvailable`, as the Updater performs + this check internally anyway. + # 0.1.3 - Ignore some lints in generated files to make pub.dev happy diff --git a/shorebird_code_push/CONTRIBUTING.md b/shorebird_code_push/CONTRIBUTING.md new file mode 100644 index 0000000..01d34a1 --- /dev/null +++ b/shorebird_code_push/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contributing + +We are happy to accept contributions! + +## Developing + +### FFI + +The Dart code in this library communicates with the Updater (part of Shorebird's +Flutter engine) via FFI. + +For an Updater function to be visible to the Dart code, it must: + +1. Be declared in c_api.rs as `pub extern "C"`. + 1. This will add the function to the `library/include/updater.h` header + file, which is generated by [cbindgen](https://github.com/mozilla/cbindgen) + when the Updater is built. +1. Be included in the generated ffi bindings. These can be regenerated using + `dart run ffigen`. +1. Android specific: be listed in + https://github.com/shorebirdtech/engine/blob/main/shell/platform/android/android_exports.lst diff --git a/shorebird_code_push/README.md b/shorebird_code_push/README.md index eb72c74..8cd1295 100644 --- a/shorebird_code_push/README.md +++ b/shorebird_code_push/README.md @@ -1,13 +1,33 @@ # Shorebird Code Push +[![Discord](https://dcbadge.vercel.app/api/server/shorebird)](https://discord.gg/shorebird) + [![License: MIT][license_badge]][license_link] -A Dart library that allows Flutter apps to get information about code push updates. +A Dart package for communicating with the [Shorebird](https://shorebird.dev) +Code Push Updater. Use this in your Shorebird app to: -WARNING: This package is in a preview state and does not work with the currently available version of Shorebird. +- ✅ Get the currently installed patch version +- ✅ Check whether a new patch is available +- ✅ Download new patches + +## Getting Started + +If your Flutter app does not already use Shorebird, follow our +[Getting Started Guide](https://docs.shorebird.dev/) to add code push to your +app. + +## Installation + +```sh +flutter pub add shorebird_code_push +``` ## Usage +After adding the package to your `pubspec.yaml`, you can use it in your app like +this: + ```dart // Import the library import 'package:shorebird_code_push/shorebird_code_push.dart'; @@ -21,29 +41,18 @@ final currentPatchversion = shorebirdCodePush.currentPatchVersion(); // Check whether a patch is available to install. final isUpdateAvailable = await shorebirdCodePush.isNewPatchAvailableForDownload(); -if (isUpdateAvailable) { - // Download the patch. - await shorebirdCodePush.downloadUpdate(); -} +// Download a new patch. +await shorebirdCodePush.downloadUpdateIfAvailable(); ``` -## Developing +## Join us on Discord! -### FFI +We have an active [Discord server](https://discord.gg/shorebird) where you can +ask questions and get help. -The Dart code in this library communicates with the Updater (part of Shorebird's -Flutter engine) via FFI. +## Contributing -For an Updater function to be visible to the Dart code, it must: - -1. Be declared in c_api.rs as `pub extern "C"`. - 1. This will add the function to the `library/include/updater.h` header - file, which is generated by [cbindgen](https://github.com/mozilla/cbindgen) - when the Updater is built. -1. Be included in the generated ffi bindings. These can be regenerated using - `dart run ffigen`. -1. Android specific: be listed in - https://github.com/shorebirdtech/engine/blob/main/shell/platform/android/android_exports.lst +See [CONTRIBUTING.md](CONTRIBUTING.md). [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT diff --git a/shorebird_code_push/example/lib/main.dart b/shorebird_code_push/example/lib/main.dart index f7f1c23..596799c 100644 --- a/shorebird_code_push/example/lib/main.dart +++ b/shorebird_code_push/example/lib/main.dart @@ -133,7 +133,7 @@ class _MyHomePageState extends State { Future _downloadUpdate() async { _showDownloadingBanner(); - await _shorebirdCodePush.downloadUpdate(); + await _shorebirdCodePush.downloadUpdateIfAvailable(); if (!mounted) return; ScaffoldMessenger.of(context).hideCurrentMaterialBanner(); diff --git a/shorebird_code_push/lib/src/shorebird_code_push.dart b/shorebird_code_push/lib/src/shorebird_code_push.dart index 69e564c..424613e 100644 --- a/shorebird_code_push/lib/src/shorebird_code_push.dart +++ b/shorebird_code_push/lib/src/shorebird_code_push.dart @@ -72,7 +72,7 @@ class ShorebirdCodePush { } /// Downloads the latest patch, if available. - Future downloadUpdate() async { + Future downloadUpdateIfAvailable() async { await _runInIsolate( (updater) => updater.downloadUpdate(), fallbackValue: null, diff --git a/shorebird_code_push/pubspec.yaml b/shorebird_code_push/pubspec.yaml index 5249e0b..2134c19 100644 --- a/shorebird_code_push/pubspec.yaml +++ b/shorebird_code_push/pubspec.yaml @@ -1,6 +1,6 @@ name: shorebird_code_push description: Check for and download Shorebird code push updates from your app. -version: 0.1.3 +version: 1.0.0 homepage: https://shorebird.dev repository: https://github.com/shorebirdtech/updater diff --git a/shorebird_code_push/test/src/shorebird_code_push_test.dart b/shorebird_code_push/test/src/shorebird_code_push_test.dart index eb2f10e..fd30ba8 100644 --- a/shorebird_code_push/test/src/shorebird_code_push_test.dart +++ b/shorebird_code_push/test/src/shorebird_code_push_test.dart @@ -91,13 +91,19 @@ void main() { group('downloadUpdate', () { test('forwards the return value of updater.nextPatchNumber', () async { when(() => updater.downloadUpdate()).thenReturn(null); - await expectLater(shorebirdCodePush.downloadUpdate(), completes); + await expectLater( + shorebirdCodePush.downloadUpdateIfAvailable(), + completes, + ); expect(loggedError, isNull); }); test('logs error if updater throws exception', () async { when(() => updater.downloadUpdate()).thenThrow(Exception('oh no')); - await expectLater(shorebirdCodePush.downloadUpdate(), completes); + await expectLater( + shorebirdCodePush.downloadUpdateIfAvailable(), + completes, + ); expect(loggedError, '[ShorebirdCodePush] Exception: oh no'); }); });