AUTHORING: the example rule, its watch deviations and its one exception

.github/workflows/ci.yml

@@ -3,9 +3,10 @@
 # Scoped to `lib` and `test` on purpose. Each `example/` is a separate Flutter
 # project with its own pubspec — several are ported upstream examples carrying
 # their own sub-projects (audioplayers' `example/server/`), and AUTHORING.md
-# says to ship those verbatim. Gating on them would make CI red for reasons
-# that are not the package's, and would pressure people into editing code the
-# repo deliberately keeps unmodified.
+# §3 keeps those as upstream wrote them, apart from listed watch deviations.
+# Gating on them would make CI red for reasons that are not the package's, and
+# would pressure people into editing code the repo deliberately keeps as
+# upstream's.
 #
 # Native code is not compiled here: these are watchOS FFI plugins, and every
 # test fakes the bindings through a `forTesting` constructor, so nothing needs

AUTHORING.md

@@ -284,11 +284,30 @@ its definition. A release build keeps the app's code in `Runner` itself: run
 stub without Flutter code).
 
 Finally, run the real native code end-to-end on the simulator. Ship the
-**upstream plugin's own example and its official `integration_test` verbatim** —
+**upstream plugin's own example and its official `integration_test`** —
 `flutter-watchos plugin port --include-example` ports both, unmodified, with a
-watchOS runner on top. Do **not** hand-write a substitute test: if an official
-test surfaces a real behavioural gap, fix the **implementation**, not the test.
-Then:
+watchOS runner on top. The example stays upstream's code, except for these
+watch deviations, each listed in the package `README.md` and
+`PORTING_REPORT.md`:
+
+- `Platform.isIOS` becomes `FlutterWatchosPlatform.isIos` where the call it
+  guards reaches a plugin with no watchOS implementation.
+- A missing `*_watchos` package is added to the example's pubspec.
+- An upstream comment with a forbidden word is reworded.
+
+If upstream's example cannot launch on the watch even with these deviations
+(for example, its start-up calls a plugin that has no watchOS
+implementation), ship a small watch demo of the app-facing API instead, and
+say why in an `## Example` section of `PORTING_REPORT.md`. The official
+`integration_test` still ships. A limit that only part of the example hits,
+such as a link the watch cannot open, is not a reason: use a deviation, or
+record the limit in the verification table.
+
+The official tests stay verbatim. Do **not** hand-write a substitute test: if
+an official test surfaces a real behavioural gap, fix the **implementation**,
+not the test. A test for behaviour the official ones do not cover goes next
+to them, named `watchos_<topic>_test.dart` so it is not taken for an upstream
+test. Then:
 
 ```sh
 cd example

README.md

@@ -164,7 +164,11 @@ A few packages need a writable directory and therefore also
 Each ported package ships the **upstream plugin's own example** (its demo
 `lib/` and, where upstream has one, its official `integration_test/`), ported
 by `flutter-watchos plugin port --include-example` with a watchOS runner on
-top, plus host-side unit tests. The example imports only the app-facing
+top, plus host-side unit tests. The example differs from upstream's only by
+the watch deviations that the package's README and `PORTING_REPORT.md` list.
+Where upstream's example cannot launch on the watch, the package ships a
+small watch demo instead, and its `PORTING_REPORT.md` says why
+([`AUTHORING.md`](AUTHORING.md) §3). The example imports only the app-facing
 plugin, and the `*_watchos` implementation registers itself through
 federation. The four Firebase packages add a smoke test, because their
 upstream examples have none. To run an integration test on the Simulator:
@@ -289,7 +293,7 @@ plugins/
 │   ├── watchos/Classes/          # native FFI (Objective-C, exported C symbols)
 │   ├── watchos/Views/            # native SwiftUI platform views (optional)
 │   ├── watchos/Package.swift     # SwiftPM manifest
-│   ├── example/                  # upstream example + integration_test, verbatim
+│   ├── example/                  # upstream example + integration_test (AUTHORING.md §3)
 │   ├── test/                     # host-side unit tests (FFI bindings faked)
 │   ├── PORTING_REPORT.md         # port detail + verification-status table
 │   ├── README.md  CHANGELOG.md  LICENSE