shorebirdtech / docs Goto Github PK

Description

It would be helpful to clearly define some of the Shorebird terms on our docs site, including but not limited to:

• Updater (Our addition to the Flutter engine, the code that downloads and applies patches. Written in Rust, source at https://github.com/shorebirdtech/updater)
• Release (and how a shorebird release differs from a play store release)
• Patch (they apply to specific releases, are downloaded on the first app launch after they've been published, are visible on the next app launch after that)
• Collaborator (an app has 1-N collaborators. A collaborator is a Shorebird user who can publish releases and patches to a given app.)

From a customer:

hello, i am getting error with shorebird
This is the information that I can give you

✓ Verifying patch can be applied to release (4.0s)
[WARN] The release artifact contains asset changes, which will not be included in the patch.
    Added files:
        base/assets/flutter_assets/assets/images/bg_button_disable.png
    Changed files:
        base/assets/flutter_assets/AssetManifest.bin
        base/assets/flutter_assets/AssetManifest.json
        base/assets/flutter_assets/fonts/MaterialIcons-Regular.otf
Continue anyways? (y/N) Yes
Creating artifact for E:\Source\finplus\build\app\intermediates\stripped_native_libs\devRelease\out\lib\arm64-v8a\libapp.so
[Process.run] C:\Users\Admin.shorebird\bin\cache\artifacts\patch\patch C:\Users\Admin\AppData\Local\Temp\cbc58a5\artifact E:\Source\finplus\build\app\intermediates\stripped_native_libs\devRelease\out\lib\arm64-v8a\libapp.so C:\Users\Admin\AppData\Local\Temp\27462852\diff.patch
✗ Exception: Failed to create diff:  (0.1s) 

Eric:

We should probably add a documentation page for that error. But what it means is that you added an image and changed your use of a font. Two things we can’t yet update with shorebird. shorebirdtech/shorebird#318

(https://discord.com/channels/1030243211995791380/1125516353370075306/1162274291073695835)

I very strongly doubt that anyone using Flutter won't have added the internet permission to their AndroidManifest.xml file, but based on my experience writing #28, this is a stumbling block that we could very easily remove.

Our headless detection is clearly not working well enough yet. We should also just add some docs about specifying CI=1 or whatever is is we need.

e.g. https://discord.com/channels/1030243211995791380/1189097166476673075/1233055119063515157

e.g. what does someone need to create a patch to your app.

How are we protecting your app data, etc.

Codemagic published a blog article on how to Shorebird with Codemagic: https://blog.codemagic.io/how-to-set-up-flutter-code-push-with-shorebird-and-codemagic/

I can add this link as an additional resource to the docs page.

See #109

We'll probably want to update this on:

1. https://docs.shorebird.dev/code_push/release
2. https://docs.shorebird.dev/code_push/patch
3. https://docs.shorebird.dev/guides/code_push_quickstart
4. https://docs.shorebird.dev/code_push/preview depending on where that work lands
5. https://docs.shorebird.dev/guides/code_push_release
6. https://docs.shorebird.dev/architecture if @eseidel wants to talk about our Dart sdk modifications
7. Update shorebird release ios-preview warning text.

Hey Shorebird team! 🌟

First of all, let me express my appreciation for your amazing work on Shorebird 🎉! We're all super excited that code push is finally possible on Flutter! 🥳

I wanted to share a solution I found for using Shorebird with the Codemagic Workflow Editor. As per your documentation, it is mentioned that Codemagic Workflow Editor doesn't support changing the build command, which is required for using Shorebird. I came up with a workaround that allows me to override the default flutter build command with Shorebird's command. I have tested this, and it works successfully on Codemagic.

Here's the setup 🎈:

1. Create a bash script (let's call it setup_shorebird.sh) with the following content:

#!/bin/bash

# 🚀 Install Shorebird
curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

echo PATH="/Users/builder/.shorebird/bin:$PATH" >> $CM_ENV

export SHOREBIRD_TOKEN="$SHOREBIRD_TOKEN"

# 🛠️ Override the flutter command
cat > flutter_override.sh << 'EOF'
#!/bin/bash

# 🧐 Check if the first argument is "build"
if [ "$1" == "build" ]; then
  # 🎯 Run the modified command
  exec shorebird release android --force -- --dart-define=ENVIRONMENT_TYPE=production
else
  # 🏃 Run the original command with the original arguments
  exec flutter "$@"
fi
EOF

# 🔒 Make the script executable
chmod +x flutter_override.sh

# 🚚 Move the script to /usr/local/bin
sudo mv flutter_override.sh /usr/local/bin/flutter

# 🎊 Print a success message
echo "Flutter override script has been installed successfully."

This script downloads and sets up Shorebird, then overrides the default flutter build command.

2. In the Codemagic Workflow Editor, add the setup_shorebird.sh script to the "Pre-build script" section.

3. Add the SHOREBIRD_TOKEN environment variable in the "Environment variables" section of the Codemagic Workflow Editor.

And voilà! 🎩✨ After completing these steps, the Codemagic build process should use Shorebird's command instead of the default flutter build.

Please note that I'm using the shorebird release android --force -- --dart-define=ENVIRONMENT_TYPE=production command to define environment variables. You can customize this as you wish or even make the script super-dynamic to accept any configuration set up in the workflow editor. 😁

I hope this workaround helps others who are looking to use Shorebird with Codemagic Workflow Editor 🌈.

Once again, thank you for your fantastic work on Shorebird 🙌!

I've had one request for this so far.

Right now we have GitHub and CodeMagic. Others have asked for BitRise and other CI configs. Instead of writing one for each config (we could link to other's docs instead?) we should consider having a generic CI page?

https://docs.shorebird.dev/guides/hybrid-app/android#verify-that-your-app-runs

A customer seemed to have missed the step, we should make it more obvious.
"In Android Studio, update the active build variant to release and run your app. Your app should work as before with no differences."

Description

Right now the snippets in the documentation have a copy button that shows when you hover over it. We could make it visible all the time so it is always clear to users that the copy function is there.

Requirements

• Make the copy always visible.

e.g. what is the difference between an app "owner" and and "editor" (e.g. collaborator).

Is it possible to restrict the ability to publish patches to certain accounts?

Our docs are still per-platform for releasing and patching, yet we support doing multiple at once.

We could even get rid of the "iOS" vs. "Android" divisions. 🤷

This command is only mentioned once in an FAQ entry and nowhere on our main site or in the console. We should mention this to make sure users know how to sign up for a plan, possibly at the end of the code push flow https://docs.shorebird.dev/code-push

There is some confusion about the build-number flag – it is not obvious that it doesn't relate to shorebird at all. The docs should call this out and we should maybe consider renaming.

Description

Finding info on the docs site is kinda hard, having a search button would be nice.

Requirements

• Add Search

Additional Context

None

fastlane is a popular way to automate iOS releasing. We should figure out how shorebird does (or doesn't) fit into this and document it.

I installed Docker for Mac. Then ran

docker compose up --build per the README.md

eseidel@erics-mbp docs % docker compose up --build
[+] Building 34.1s (9/9) FINISHED                                                                                                                                                                             
 => [internal] load build definition from Dockerfile                                                                                                                                                     0.0s
 => => transferring dockerfile: 159B                                                                                                                                                                     0.0s
 => [internal] load .dockerignore                                                                                                                                                                        0.0s
 => => transferring context: 275B                                                                                                                                                                        0.0s
 => [internal] load metadata for docker.io/library/node:lts                                                                                                                                              1.7s
 => [internal] load build context                                                                                                                                                                        0.0s
 => => transferring context: 988.00kB                                                                                                                                                                    0.0s
 => [1/4] FROM docker.io/library/node:lts@sha256:671ee8d49ce2a691fc3082203c5deb9522e0c80042aa0ff40c07f4a25e63668a                                                                                       15.9s
 => => resolve docker.io/library/node:lts@sha256:671ee8d49ce2a691fc3082203c5deb9522e0c80042aa0ff40c07f4a25e63668a                                                                                        0.0s
 => => sha256:4672913f7ad129a34409e7d040621df203218b1cfa91fa0fee3377b065fa0feb 2.21kB / 2.21kB                                                                                                           0.0s
 => => sha256:9280a10caf40b31effb3fd770e9eeef6ef656dd7ccd7b8bb93005a589dc55369 7.58kB / 7.58kB                                                                                                           0.0s
 => => sha256:dc80b8cdbfd36cb20231d807a50d704945d1df4da8f6e23197ccfcb629970491 53.71MB / 53.71MB                                                                                                         6.0s
 => => sha256:5884e7f2c8c61aa845de4902fc29639b58861ae6c2d80bafe82082c0456c0740 5.15MB / 5.15MB                                                                                                           0.3s
 => => sha256:1b792b01ed3c8dc1488cd8aac41ab7d49bb17f3fa22b2e6c846078cec81a1c00 10.87MB / 10.87MB                                                                                                         1.1s
 => => sha256:671ee8d49ce2a691fc3082203c5deb9522e0c80042aa0ff40c07f4a25e63668a 1.21kB / 1.21kB                                                                                                           0.0s
 => => sha256:8f993d5b17f32f4b8a535c25e182e5d8412625beee450e513ca57036e8fdd6dc 54.68MB / 54.68MB                                                                                                         6.2s
 => => sha256:c26edf98ece5babdb6b65e76738cef2c2d05e7075161753d3ba95cd84480d211 189.73MB / 189.73MB                                                                                                      12.8s
 => => sha256:ef4553a29827be949323a49bbe126aac00893203a3234abe3a2915aa4b0b768a 4.20kB / 4.20kB                                                                                                           6.2s
 => => extracting sha256:dc80b8cdbfd36cb20231d807a50d704945d1df4da8f6e23197ccfcb629970491                                                                                                                0.7s
 => => sha256:f12d0fbf1676444f72f7a86719bd3c8a5ef70c77eaee331304d13da832785a54 45.58MB / 45.58MB                                                                                                         9.0s
 => => sha256:14531ce9f0a46be86d89363abbf533499226c7734e56c3fbb7d70a8da9562be7 2.28MB / 2.28MB                                                                                                           6.6s
 => => sha256:5f64eb351b344b535e5676014358c3045349fae2d10e4d45048067a26b17229c 452B / 452B                                                                                                               6.8s
 => => extracting sha256:5884e7f2c8c61aa845de4902fc29639b58861ae6c2d80bafe82082c0456c0740                                                                                                                0.1s
 => => extracting sha256:1b792b01ed3c8dc1488cd8aac41ab7d49bb17f3fa22b2e6c846078cec81a1c00                                                                                                                0.1s
 => => extracting sha256:8f993d5b17f32f4b8a535c25e182e5d8412625beee450e513ca57036e8fdd6dc                                                                                                                0.7s
 => => extracting sha256:c26edf98ece5babdb6b65e76738cef2c2d05e7075161753d3ba95cd84480d211                                                                                                                2.1s
 => => extracting sha256:ef4553a29827be949323a49bbe126aac00893203a3234abe3a2915aa4b0b768a                                                                                                                0.0s
 => => extracting sha256:f12d0fbf1676444f72f7a86719bd3c8a5ef70c77eaee331304d13da832785a54                                                                                                                0.7s
 => => extracting sha256:14531ce9f0a46be86d89363abbf533499226c7734e56c3fbb7d70a8da9562be7                                                                                                                0.0s
 => => extracting sha256:5f64eb351b344b535e5676014358c3045349fae2d10e4d45048067a26b17229c                                                                                                                0.0s
 => [2/4] WORKDIR /app                                                                                                                                                                                   0.3s
 => [3/4] COPY . .                                                                                                                                                                                       0.0s
 => [4/4] RUN npm install                                                                                                                                                                               14.4s
 => exporting to image                                                                                                                                                                                   1.7s
 => => exporting layers                                                                                                                                                                                  1.7s
 => => writing image sha256:a2234d47056bb6df713b5821ba01c6fd103e1e9de7016a224290ae89358eb5e2                                                                                                             0.0s
 => => naming to docker.io/library/docs-shorebird-docs                                                                                                                                                   0.0s
[+] Running 2/2
 ⠿ Network docs_default      Created                                                                                                                                                                     0.0s
 ⠿ Container shorebird-docs  Created                                                                                                                                                                     0.1s
Attaching to shorebird-docs
shorebird-docs  | 
shorebird-docs  | > [email protected] start
shorebird-docs  | > docusaurus start --host 0.0.0.0
shorebird-docs  | 
shorebird-docs  | sh: 1: docusaurus: not found
shorebird-docs exited with code 127

It's not clear at the moment that shorebird in an add-to-app scenario only works with the release build variant. This should be called out/made more prominent.

e.g. how the patch check works. Why it's secure, etc.

Description

https://docs.shorebird.dev/code_push/release does not mention about shorebird release --artifact apk

https://discord.com/channels/1030243211995791380/1125516353370075306/1127246820570038422

When I execute the command shorebird release android --flutter-version=3.22.2 --artifact=apk to package the APK, an error "Failed to generate v1 signature" occurs. The error's cause is due to the expiration of the keystore's PrivateKeyEntry. However, using flutter build apk --release does not have this issue. Due to specific requirements, I cannot update the keystore. Is there a way to bypass the PrivateKeyEntry expiry check when executing shorebird release android to allow the APK to be packaged successfully?

(Branched from #87)

1. https://docs.shorebird.dev/status to move iOS from a "coming soon" to a "usable but not production-ready" preview state.
2. https://docs.shorebird.dev/faq#what-platforms-does-shorebird-support-does-it-support-ios same as above

Many CI systems rely on the use of an export options plist (see the iOS tab at https://docs.codemagic.io/yaml-quick-start/building-a-flutter-app/#configure-scripts-to-build-the-app). There isn't a lot of great documentation for this file from Apple or elsewhere. We should provide at least a cursory explanation of what this file is and how/why to use it in our docs.

https://docs.shorebird.dev/guides/hybrid-app/android#update-your-android-app-to-use-the-downloadshorebirddev-maven-repository

url '../my_flutter_module/build/host/outputs/repo'

We just spoke with a customer who had correctly changed the path, but not to the correct name (changed to the name of the package rather than the on-disk location).

Encouraging users to verify that path might help?

Some users would like to use Shorebird in a headless environment.

Should be possible with shorebird login:ci or otherwise copying ones oauth token from a local machine to the headless machine.

We could write some docs explaining such other than:
https://docs.shorebird.dev/ci/generic/

Description

The current codemagic "advanced example" is this:

workflows:
  advanced-example:
    name: Advanced Example
    environment:
      vars:
        TYPE: 'patch' # Can be 'patch' or 'release'
      groups:
        # Exports the SHOREBIRD_TOKEN environment variable
        - shorebird
      flutter: stable
    scripts:
      - name: 🐦 Setup Shorebird
        script: |
          # Install Shorebird
          curl --proto '=https' --tlsv1.2 https://raw.githubusercontent.com/shorebirdtech/install/main/install.sh -sSf | bash

          # Add Shorebird to PATH
          echo PATH="$HOME/.shorebird/bin:$PATH" >> $CM_ENV
      - name: 🙌 Shorebird Build
        script: |
          echo "➡️ Using type: $TYPE"

          # If type is neither "patch" nor "release", exit with error
          if [ "$TYPE" != "patch" ] && [ "$TYPE" != "release" ]; then
            echo "TYPE must be either 'patch' or 'release'"
            exit 1
          fi

          # Check type and run corresponding command
          if [ "$TYPE" == "patch" ]; then
            echo "🩹 Running patch command"
            shorebird patch android --force
          elif [ "$TYPE" == "release" ]; then
            echo "🚀 Running release command"
            shorebird release android --force
          fi

However, you will probably add a publishing section to your file so that you can get your apps on the stores. The problem is that when you do this, it will try to submit to the App Store you configured, even if you run a patch. Since no file is produced from the patch command, this makes the workflow fail.

I would suggest changing this example to have two workflows, one with the patch command and the other with the release command.

We've actually implemented this in our codemagic.yaml, as well as including a separate iOS and Android workflows, but it keeps it clean by reusing steps where possible. If you'd like, I'd be happy to clean off our domain-specific stuff and put up a PR on this page.

Thanks!

See https://github.com/orgs/community/discussions/42655.

We've had a few people ask.

Should be straightforward to do, similar to the github one:
https://docs.shorebird.dev/ci

I suspect someone in the community who happens to use both could write a great doc if we don't get to it first.

Topics to include (or at least include links to):

1. Shorebird uses the version reported by the compiled app to determine Release version
2. By default, this is the version in pubspec.yaml, BUT
3. It can be changed by the user (e.g., with fastlane)
4. How Info.plist and build.gradle consume version from pubspec (or not)

Description

When setting up flavors and you follow the Shorebird docs for Android, the docs mention the following the example:

defaultConfig {
    ...
}

+    flavorDimensions "track"
+    productFlavors {
+        internal {
+            dimension "track"
+            applicationIdSuffix ".internal"
+            manifestPlaceholders = [applicationLabel: "[Internal] Shorebird Example"]
+        }
+        stable {
+            dimension "track"
+            manifestPlaceholders = [applicationLabel: "Shorebird Example"]
+        }
+    }

buildTypes {
  ...
}

However, the line applicationIdSuffix ".internal" is optional and isn't required. I can also break the app if you have something like Firebase set up that depends on the package name.

In Discord, there was a customer who that this issue: https://discord.com/channels/1030243211995791380/1158737883511926784

Possible solution

A possible solution could be to mention that the applicationSuffix line is optional:

defaultConfig {
    ...
}

+    flavorDimensions "track"
+    productFlavors {
+        internal {
+            dimension "track"
+            // The `applicationIdSuffix ".internal"` line is optional and can be omitted.
+            // However, be cautious when using it with services like Firebase, which 
+            // may rely on consistent package names.
+            applicationIdSuffix ".internal"
+            manifestPlaceholders = [applicationLabel: "[Internal] Shorebird Example"]
+        }
+        stable {
+            dimension "track"
+            manifestPlaceholders = [applicationLabel: "Shorebird Example"]
+        }
+    }

buildTypes {
  ...
}

Description

On the main webpage there should a deep description on how Shorebird works and how it affects the project. Also it should be clear there if and how we can undo Shorebird if we decide to not use it anymore.

Could include git commands?

Description

Comparing the output of flutter build apk --release vs. shorebird build apk --release should give you a rough idea.

We get regular requests on how to produce an apk to distribute outside the stores.

Another one this morning:

I distribute my app via Android APK only and getting user's to update their app is a struggle. My app is built with Flutter.

I wanted to confirm if Shorebird makes it possible for my user's app to always automatically update whenever I push a new build to production

A mention in https://docs.shorebird.dev/code_push/release about how to use --artifact apk or a dedicated guide on how to release for sideloading would help these users I think.

Some customers worry that we see their code, we don't. We should make that clear in an FAQ.

A customer had this question here and I don't think we currently provide guidance.

Description

We have some images in the docs which serves as support for what is being documented. But some of them are too small, or they have too many details (like a screenshot) to be readable.

The codemagic screenshot in this page is a good example.

We could make a zoom button that would open the image in a modal or something like that, allow the user to focus on the image and be able to better "read" it.

Requirements

• Implement a way to be able to zoom/focus an image in the docs.