Staging Patches

This guide will walk through how to validate a patch in Patchwing’s staging environment before promoting the patch to production.

Prerequisites

This guide assumes the Patchwing command-line is installed on your machine and that you are logged into an account. Refer to the getting started instructions for more information.

Create a Project

Create a new project using patchwing create example --empty.

This will create a patchwing.yaml file in the root of your project. This file contains your Patchwing app_id. Your app_id is not secret and can be checked into source control and freely shared.

The generated patchwing.yaml should look something like:

# Your app_id is not a secret and is just used to identify your app
# when requesting patches from Patchwing's servers.
app_id: ee322dc4-3dc2-4324-90a9-04c40a62ae76
# auto_update controls if Patchwing should automatically update in the background on launch.
# If auto_update: false, you will need to use package:patchwing_code_push to trigger updates.
# https://pub.dev/packages/patchwing_code_push
# Uncomment the following line to disable automatic updates.
# auto_update: false

Create a release

Now that we’ve created our apps on patchwing, we need to create releases (one for each platform). To create a release, we’ll use the patchwing release command.

patchwing release android

patchwing release ios

patchwing release macos

We can verify the releases were created successfully by visiting Patchwing console.

You should also submit the generated app bundles to the Play Store and submit the generated ipa to the App Store.

Creating a patch

Now that we have our releases on the Play Store and App Store, we can create a patch using patchwing patch. For the sake of this example, let’s set the backgroundColor of the Scaffold to Colors.cyan in lib/main.dart:

import 'package:flutter/material.dart';

void main() {
  runApp(const MainApp());
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
+       backgroundColor: Colors.cyan,
        body: Center(
          child: Text('Hello World!'),
        ),
      ),
    );
  }
}

Now that we’ve applied the changes, let’s create a patch:

patchwing patch android --track=staging

patchwing patch ios --track=staging

patchwing patch macos --track=staging

Preview the release

Next, preview the app release locally on a device or emulator, use patchwing preview.

# Preview the release in the staging environment
patchwing preview --track staging --app-id ee322dc4-3dc2-4324-90a9-04c40a62ae76 --release-version 1.0.0+1

Patchwing will download the release and run it on your device in the staging environment.

The first time the app is re-launched, we should still see the white Scaffold and patchwing will detect and install the patch in the background. Kill and re-launch the app a second time to see the applied patch with the cyan Scaffold background.

If all went well, you should see the patch was applied after re-launching the app a second time. Congrats, you’ve validated your patch in the staging environment 🥳

Promote the patch

Now that you have validated the patch, you can push the patch to all devices by promoting it to production from the Patchwing console. Navigate to the release details page, choose “Change Track”, and select “stable” in the dialog that appears.

Screenshot of the 'switch track' option in the patch context menu

You can also use the Patchwing CLI to promote the patch.

You can promote the patch to the stable channel using the following command:

patchwing patches set-track --release-version 1.0.0+1 --patch-number 1 --track stable

At this point, you have a setup which allows you to preview patches locally before promoting them to production 🎉