Skip to content

Latest commit

 

History

History
109 lines (71 loc) · 21.5 KB

CONTRIBUTING.md

File metadata and controls

109 lines (71 loc) · 21.5 KB

Contributing to SMF Flutter CLI

Thank you for your interest in contributing to SMF Flutter CLI! This document provides guidelines and information for contributors.

Code of conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

How can I contribute?

Reporting bugs

  • Use the GitHub issue tracker
  • Include detailed steps to reproduce the bug
  • Provide your environment details (OS, Flutter version, etc.)
  • Include error messages and stack traces

Suggesting enhancements

  • Use the GitHub issue tracker with the "enhancement" label
  • Describe the feature and its benefits
  • Provide use cases and examples

Submitting code changes

  1. Fork the repository
  2. Create a branch named after the change type (git checkout -b feat/amazing-feature, or fix/..., docs/...)
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all checks pass (melos run check)
  6. Commit using Conventional Commits (git commit -m 'feat(go_router): add amazing feature')
  7. Push to the branch (git push origin feat/amazing-feature)
  8. Open a Pull Request with a Conventional Commit as its title. It is squash-merged, and the commit takes the title as its only line, so CI checks it. Mark a breaking change with ! in the title (feat(contracts)!: ...).

Development setup

CI pins Dart 3.12.2, and the output of the formatter depends on its version, so develop with that Dart, which Flutter 3.44.2 comes with.

  1. Clone the repository
  2. Install Melos and the Mason CLI: dart pub global activate melos and dart pub global activate mason_cli
  3. Install dependencies and bundle bricks: melos bootstrap
  4. Run all checks: melos run check (format, analyze, banlist, tests)

The bundles in lib/bundles/ are generated from the bricks, so change the brick, run melos bootstrap and commit both. When a change alters what an app renders, update the snapshots of the CLI or of the fixtures with SMF_UPDATE_SNAPSHOTS=1 dart test test/snapshot_test.dart in the package, and review their diff.

CI generates each app of its matrices with smf create --strict, which stops on a warning about what the app is made of, such as a destination that no main navigation leads to. Some apps warn on purpose: the app of settings alone has no route to start on. Tests declare these apps and the codes of their warnings, in packages/smf_flutter_cli/test/matrix_test.dart and in matrix_app_tests_test.dart and broken_providers_test.dart of packages/smf_pipeline/fixture_registry/test/. When a change makes an app warn, these tests fail and print the warnings that the apps have now. Then either change the app so that it does not warn, or declare the new warnings.

CI also runs the tests with coverage, and fails when they do not cover a line or a branch of lib/. To check it locally, install the coverage tool with dart pub global activate coverage, then run melos run test:coverage and melos run coverage:check, which names each line and branch that no test reaches. Code that no test can run goes between // coverage:ignore-start and // coverage:ignore-end, with the reason in a comment.

Besides these checks, CI generates apps with Flutter and runs flutter analyze on each, then flutter test with the tests that packages keep for the apps in app_tests/, which packages/smf_flutter_cli/lib/matrix_app_tests.dart and packages/smf_pipeline/fixture_registry/lib/matrix_app_tests.dart register. To run it locally, with flutter on the PATH:

dart run packages/smf_flutter_cli/tool/matrix.dart /tmp/smf_apps
dart run packages/smf_pipeline/fixture_registry/tool/matrix.dart /tmp/smf_fixture_apps
dart run packages/smf_pipeline/fixture_registry/tool/several_providers_matrix.dart /tmp/smf_several_providers
dart run packages/smf_pipeline/fixture_registry/tool/broken_providers_matrix.dart /tmp/smf_broken_providers

An app of a provider of the CI role also runs the commands of its CI in a clone of a commit of the app, as on its first push, so the clone has no .env and nothing else that the .gitignore of the app keeps out. The apps with every module leave this out. For one of them, --ci-commands --app <name> [--build] <app> of the matrix tool of the CLI runs the commands, and --build also builds the app in a second clone. The job Android (<app>) of CI runs this on its app, and the first job of its matrix adds --build. That first job also checks that a release build of its app stops without the arguments that give the app the values of .env, with the text of the env role, and builds with them (test/env_release_build_test.dart of smf_contracts, which needs the app in SMF_RELEASE_APP). The commands need bash and git, so no job on Windows runs them.

To check only some apps of the matrix, name them after the directory, such as 'go_router with layout'. The apps with every module grow with the product of the numbers of providers of the roles that take one: there is one for each combination, such as one for each state manager. So the tools take a pairwise covering of them, in which every pair of providers of two roles is in one of the apps. --combinations 3-wise or --combinations all before the directory takes more. A role with a mode option, whose values each make another app, has the apps with every module once more for its other values, such as every module (fake_router, fake_di, fake_bloc) --clock-hours=12 in the fixtures. A run of the matrix checks a few of them, once: those that have each value with each provider. --every-module and --app leave them out, and so do the apps that CI builds and starts, which have the first value, as an app that a user generates without the option. An app test reads the value from the choice of the role (MatrixApp.hook), never from the name or the options of the app. With --every-module before the directory, the tools check only the apps with every module, and with --app and the name of one as well, such as --every-module --app 'every module (riverpod)', only that one. --shard 1/2 before the directory checks only the first of two shares of the apps. The third command runs the app tests of the CLI and of its modules in one app, next to other providers of the roles of those modules and a start-up that waits for a timer, so that they pass whatever else an app has. It takes no names of apps. In that app, the tests of the analytics role and of the crash reporting role also check that each call reaches every provider of the role once, whatever the other providers do with it. The fourth command checks the tests themselves, since a test of a role that passes whatever the provider of the role does checks nothing. It generates a small app for each fixture provider of a role with one known bug (brokenProviders() in packages/smf_pipeline/fixture_registry/lib/broken_providers.dart) and runs there the app tests that apply to it: the tests of the role that the registry names must fail on the bug, with the reason it gives for each, and every other test must pass. It does the same for the apps of brokenModuleApps(), whose tests must fail for what a module does: the walk of the routes must fail on a guard that nothing opens for the tests. CI runs it in a job of its own, Generated apps (broken providers). Each role whose contract the app tests check needs such a provider, or an exemption with its reason, and a test of the fixture registry fails otherwise. A module whose start-up or services call a platform channel keeps the mocks of its platform side with its app tests and declares them (MatrixAppTest.mocks). A module whose code reads values of .env gives its app tests values for its keys (MatrixAppTest.envValues): the matrix writes them into .env of each app with the module and runs flutter test with the arguments of the provider of the env role. The matrix sets them up before the tests of every module of an app with the module. A module with a guard of the routes opens the guard in those mocks, so that the tests of the other modules see the screens of the app; the walk of the routes fails on a guard that does not allow, by its name. In a directory whose path has letters beyond ASCII, the matrix analyzes the apps with dart analyze, as flutter analyze of Flutter 3.44 and 3.47 fails there.

CI also runs the tests on macOS and Windows, and on all three systems it generates apps in directories whose names have a space and letters beyond ASCII. A job named Plan runs the matrix tools with --plan, which print the plan of the jobs that check, build and start the apps as JSON. Each of those jobs takes one shard or one app of the plan:

  • the shards of the matrices;
  • a pairwise covering of the apps with every module, which CI builds for Android on Linux and for the iOS simulator on macOS, and checks on Windows;
  • a pairwise covering of those without the modules whose steps need an external service, which it starts on devices;
  • the app with every module of each provider of the app entry, which it archives with Crashlytics on macOS and configures with Firebase to start it, and on Android to send it a push message.

A job on Windows also runs the install script of the Firebase CLI. The workflows name neither the modules nor the apps of these jobs: the matrix tool of the CLI generates each app with --create --app, named after the providers of the roles that take one other than the first of each, such as android_app and android_app_riverpod. So the jobs of a new provider of a role, such as a second app entry, which owns the Android and Xcode projects, come from the plan rather than from a change of CI. tools/workflow_apps_test.dart fails when a workflow selects an app of a matrix tool by a name it writes, names the modules of an app with -m, refers to the package of a module outside a step that runs its tests or a tool of it with dart run, but for the exceptions it lists with their reasons, checks a whole selection of apps in one job rather than its app or shard of the plan, or adds the tests of the matrix to an app without --app, which names the app of the plan that the job generated. It also fails when a step builds an app as a release, directly or in a test, without the arguments of the flutter tool that give the app its values. --create writes them next to each app, and .github/scripts/each_app.sh --tool-arguments passes them to the build. Every night, CI runs the jobs with Flutter on each stable release that the generated apps allow instead of the pinned one: the jobs on Linux on all of them, and those on macOS and Windows on the oldest and on the latest patch of each minor version. So a release of Flutter that breaks the generated apps shows up before users run into it. With the latest release, the jobs of the matrices check every combination of the providers, or a 3-wise covering of more than 100, and the job of the broken providers runs only with that release. The nightly run also installs smf_flutter_cli from pub.dev, as a user does, and on each of those releases generates with it the apps with every module of that release, analyzes and tests them and builds them for Android. A failure there affects the users of the published version, and its fix needs a release.

CI also starts apps on an Android emulator and on an iOS simulator, with a check as the entry of the app, which writes whether the app started and showed its first screen. The CLI keeps it in app_tests/start: it knows no module, only main() in lib/main.dart, which every app has whichever module provides its entry. When the start-up of the app throws, the app shows the screen of a failed start in place of its first screen. The check then fails with the first line of the error, prints the error with its stack trace to the log of the device, and runs no probe. Once the first screen of an app that started settled, the check also runs the probes of the tests of the app, for at most a minute in all, and fails on the problems they find: the walk of the routes goes to the locations that need no values, and expects the target of a guard of the routes in place of each location that the guard keeps the user from, and otherwise the screen that the app starts on in place of a location in a flow that is over; the probe of the DI role resolves each service of the app without calling it; the probe of the preferences role saves values under keys of its own, reads them back and removes them; the probe of shared_preferences opens the preferences again and reads back what it saved, as the platform returns it; the probe of firebase_auth compares the user of the session of the app with the one that the Firebase SDK has on the device, without signing anybody in; the probe of the notifications role checks that the permission of the app agrees with what the provider says, and that no tap on a notification launched the app; the probe of local_notifications checks that the channel of the app on Android has its name and a high importance; the probe of the push role checks that no tap on a message launched the app and that the app has the address that the provider gives; the probe of firebase_messaging checks that this address, once the app has one, is the registration token that the Firebase SDK has on the device, and then asks the script for a push message to that address, which CI sends to the app with Firebase on Android; the probe of the purchases role checks that the access of the app is the one that the provider gives; the probe of revenuecat checks that RevenueCat is configured exactly when the app has a key, and then that the access and the plans of the app are those that the RevenueCat SDK gives; and the probe of onboarding finishes the onboarding that a first launch shows, and checks that the app saved that and left the screen of the onboarding. A probe depends on no other: it holds whichever probes ran before it. A test declares its probe in MatrixAppTest.startProbe, and the matrix tool lists the probes of the tests that it adds to an app in integration_test/start_probes.dart. CI starts a pairwise covering of the apps with every module but the modules whose steps need an external service, such as Firebase, and the app with every module of each provider of the app entry, which it configures with tool/configure_firebase.dart in a Firebase project of its own. Only the runs of the Build workflow register a new app in that project, such as the app of a new provider of the app entry in the run of its pull request into main. CI activates the version of the FlutterFire CLI that smf_firebase_core activates on the machine of a user, which packages/smf_modules/smf_firebase_core/tool/flutterfire_version.dart prints, and tools/flutterfire_version_test.dart fails when a workflow or a script of CI writes a version of the FlutterFire CLI of its own, or activates the CLI without a version. .github/scripts/start_app.sh builds an app with the check, installs and launches it with adb or xcrun simctl, and waits for the result. To generate the apps that CI starts without Firebase, each in a directory of its own in /tmp/smf_start, run dart run packages/smf_flutter_cli/tool/matrix.dart --create --without-external-steps /tmp/smf_start start_app. To start one of them with the check, on a running Android emulator or device, or on a booted iOS simulator:

dart run packages/smf_flutter_cli/tool/matrix.dart --add-app-tests --without-external-steps --app 'every module (bloc)' /tmp/smf_start/start_app packages/smf_flutter_cli/app_tests/start
cd /tmp/smf_start/start_app
<repository>/.github/scripts/start_app.sh android <device> 240   # such as emulator-5554
<repository>/.github/scripts/start_app.sh android <device> 240 release
<repository>/.github/scripts/start_app.sh ios <UDID of the simulator> 240

--app names the app with every module that the app was generated as, such as 'every module (riverpod)' for start_app_riverpod, and --without-external-steps goes with it when --create had it. The tool then adds the tests of that app that have a probe, with the files that they read, and their dev dependencies with flutter pub add. It also writes the arguments that build the app with its values, such as --dart-define-from-file=.env, which the script passes to the build. With --env-values <file> after --app, the tool writes the values of a file of yours, lines KEY=value in the forms of .env, into the lines of .env of the app that have no value yet, such as the key of the Test Store of RevenueCat, and prints only their keys. To start an app of yours that smf create generated, leave out --app and --without-external-steps: the check then runs no probe, and the script builds the app without such arguments. So the tool refuses --env-values there, since the values would not reach the build. The third argument of the script is how many seconds the app has to start once the device has it. The build itself has no limit, as it can take minutes longer on a busy machine, and the install has a limit of its own, which the script sets. With release after the seconds, on Android only, the script builds a release app for the ABI of the device. R8 shrinks that app just as it shrinks the app that a user installs. The script reads the result from the log of the device, because it cannot read the files of a release app. CI also starts the first app that it starts on Android this way, after its debug start. The script finds the Android SDK through ANDROID_HOME, or where Android Studio installs it. flutter run -d <device> -t integration_test/start_check.dart runs the check too, and prints SMF_START_CHECK: passed, or SMF_START_CHECK: failed: and the problems. An app with Firebase starts only once tool/configure_firebase.dart configured its flavor, as its README says.

After the mode, the script takes answers, <name>=<command>. Once the start check passed, it runs the command for the request that a probe of the app wrote, and fails unless the app then reports that the answer passed. It runs only the answers that the probes of the app ask for, which the tool lists next to the start check, and skips the others with a notice. CI sends the app with Firebase a push message this way, with the answer firebase_messaging and the key of a service account of the Firebase project. To do the same with a debug app on a device of yours, configured for a project of yours, set SMF_FIREBASE_PROJECT, and SMF_FIREBASE_SERVICE_ACCOUNT to the path of a key of that project. Then add "firebase_messaging=cd '<repository>/packages/smf_modules/smf_firebase_messaging' && dart test test/push_delivery_test.dart" after the seconds. CI grants premium access in RevenueCat to the apps that it starts without external services the same way, with the answer revenuecat, a secret key of its RevenueCat project, and the key of the Test Store of that project in the secret CI_APP_ENV, which the tool writes into .env. To do the same in a RevenueCat project of yours, put its Test Store key into a file as REVENUECAT_TEST_KEY=<key> and give that file to --add-app-tests --env-values. Then set SMF_REVENUECAT_SECRET_KEY to the path of a file with a V2 secret key of that project that may read and write customers and read the project and its entitlements, and add "revenuecat=cd '<repository>/packages/smf_modules/smf_revenuecat' && dart test test/grant_access_test.dart" after the seconds of a debug start.

The jobs with Flutter are many, mostly one for each app or shard of the plan, those on macOS among them, and take about half an hour, so only pushes to main and pull requests into main run them. A pull request into another branch, such as one that collects the pull requests of a larger change, gets the job of the checks and the check of its title. The jobs with Flutter run once that branch goes into main through a pull request of its own, which is merged with a merge commit, so that the squash commit of each of its pull requests reaches main as it is. To run every job on a branch before that, use Run workflow on the Build workflow in the Actions tab. A new run of Build cancels the run of the same pull request that is still in progress, and the run of a pull request stops once it is merged or closed.

The job CI sums up the jobs of .github/workflows/build.yml: it fails when any of them failed or was cancelled, and when one was skipped in a run that runs every job. The ruleset of main requires the checks CI and PR title before a pull request can be merged. A new job in build.yml goes into the needs of CI, and a test in tools/ fails when it does not.

How the repository is organized, how its generated apps are tested and what its CI runs is at doc.saymyframe.com/contributing, and how to write a module at doc.saymyframe.com/extending. AGENTS.md has the repository layout, the module-independence rules and the conventions for generated files and tests in the form for AI coding agents: the same facts, in full and in one file.

Code style

  • Follow the Dart style guide; CI checks formatting with Dart 3.12.2
  • very_good_analysis is enabled in every package
  • Use Conventional Commits with the package as scope (fix(contracts): ...); versions and changelogs are generated from them
  • Add tests for new functionality

Copyright and licensing

By contributing to this project, you agree that your contributions will be licensed under the Apache License, Version 2.0.

When submitting code, please ensure you have the right to license your contributions under the Apache License.

Questions?

If you have questions about contributing, please contact us at [email protected] or open an issue on GitHub.

Thank you for contributing to SMF Flutter CLI!