Skip to content

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

Merged
MAUstaoglu merged 1 commit into
mainfrom
authoring-example-exception
Oct 24, 2026
Merged

MAUstaoglu merged 1 commit into
mainfrom
authoring-example-exception

Conversation

@MAUstaoglu

Copy link
Copy Markdown
Member

AUTHORING.md §3 said to ship upstream's example verbatim, and nothing more. This PR writes the whole example rule down.

Already decided, never written down. Two rules were settled before the launch but never reached the docs:

  • An upstream example may carry three listed watch deviations, each listed in the package README 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.
  • A test for behaviour the official tests do not cover goes next to them, named watchos_<topic>_test.dart, never in their place.

New exception. When upstream's example cannot launch on the watch even with those deviations, the package ships a small watch demo of the app-facing API instead. Its PORTING_REPORT.md says why, in an ## Example section, and 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. The first case is #9: upstream's main() awaits flutter_timezone, which has no watchOS implementation.

The README's "Examples & tests" section and the ci.yml header now say the same thing. #24 brings our own written-by-us examples in line with the rule.

Docs and a workflow comment only. The word check and the README snippet check pass.

AUTHORING §3 said to ship upstream's example verbatim. Spec 0006 Decision 1d
already allowed three listed watch deviations and supplementary
watchos_<topic>_test.dart tests, but the docs never said so. They do now, in
AUTHORING, the README and the ci.yml header.

New: when upstream's example cannot launch on the watch even with those
deviations, the package ships a small watch demo of the app-facing API, and
its PORTING_REPORT.md says why in an "## Example" section. The official
integration_test still ships. A limit that only part of the example hits is
not a reason.
@MAUstaoglu
MAUstaoglu merged commit 6603d6b into main Oct 24, 2026
2 checks passed
@MAUstaoglu
MAUstaoglu deleted the authoring-example-exception branch October 24, 2026 18:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant