Open
Description
In order to reduce maintenance costs and improve DX of this repo, I plan on updating and/or deprecating a majority of the samples.
After the changes, samples will fall into two categories:
- quickstarts - the minimum required code needed to demo a specific feature or API.
- demo apps - apps that are explicitly meant to demo Flutter, not a feature.
For more info on sample types, read the contributing docs.
For Googlers with too much time on their hands, read the long version of the motivation at go/dash-sample-code
Motivations
- Samples are only useful if they don't require explanation. Far too many of our samples cover topics that are too complex to be useful as samples on their own (i.e. add_to_app samples). Flutter developers would be better off if complex topics were accompanied by explainer text, as in cookbook recipes or codelabs or reference documentation.
- Multi-feature demo apps don't make good samples. Again, far too many of of samples are overly complex, but because we've designed them that way. For example, the deep-linking sample is an entire app that happens to demo deep linking. It should be reduced to it's absolutely necessary parts. Feature-rich apps should have a reason to be feature-rich. For example, the forth-coming date_planner app, which is explicitly being written to be a full demo app.
- The samples repo isn't very useful. In the week prior to 11/27, the most visited sample (compass_app) had >1000 unique visitors. In the same week, the accompanying docs had >10k unique visitors. The sample with the most views in the last week that doesn't have accompanying docs was visited a few hundred times.
- AI is coming. In the the not-too-distant future, samples will be irrelevant. Now is a great time to start slowly migrating toward a world without samples and preparing our developers for that future.
Proposed updates
The following are all the changes I plan on making.
Changes to existing samples
- compass_app - migrate to flutter website repository
- Background isolate channels and isolate_example - Combine and simplify samples. Link to dart-lang/samples as an additional resource.
- ios-app-clip - migrate to website to accompany existing docs, create ticket to ensure the documentation page sufficient (or deprecate if the sample doesn't add anything)
- add-to-app - There should only be one add-to-app quickstarts that demos the recommended way to add Flutter to an ios or android app. More explanation in ticket.
- desktop-photo-search - Expand to mobile and web, maybe simplify business usecase logic. rename something like 'multiplatform_sample'.
- [desktop-photo-search] Turn sample into the canonical multiplat sample #2513
- platform_design This sample should be rolled into above.
- navigation_and_routing - This will be split up and simplified.
Samples to add
- cupertino_gallery - This should be similar to material_3_demo.
- navigator 2.0
Samples to deprecate
- asset_transformation - This should be demonstrated in the package repository
- code_sharing - This topic is well documented in the new architecture guidance docs and sample
- Context_menus -> This is more appropriate for API reference documentation. (I'll create website ticket to document it in the docs or the API docs)
- Deeplink-store-example -> Deprecate in favor of the go_router example that includes deep-linking
- Experimental directory - deprecate all. The samples repo should represent the SDK right now. Samples demoing future features should remain as PRs until the sample passes CI on the stable channel
- Flutter-maps-firestore - Quickstarts should sample one feature
- [flutter-maps-firestore] retire sample #2524 * Form app - Deprecate, as this is covered in the documentation
- game_template - This is being deprecated in favor of the flutter/games repository
- homescreen_widgets - this should live in the package repository
- infinite_list - This is thoroughly covered on docs.flutter.dev
- [infinite_list] retire sample #2533
- place_tracker - Overly complex, redundant to other google_maps samples
- provider_counter and provider_shopper - 3P libraries shouldn't be documented here unless they're filling a gap in the Flutter SDK and not sufficiently documented elsewhere
- simplistic_calculator - We don't need multiple samples demoing desktop functionality
- Veggie seasons - deprecate in favor of wondrous, date_planner, etc. This was written to have a demo app in the Apple app store, but it hasn't been in the app store for a long time.
TBD
- simplistic_editor - important, but way complex. idk
Repo improvements, etc
- Migrate to pub workspaces after 3.7 release #2499
- [samples index] Sunset Visual Samples Index #2507
- [testing_app] Update and fix the testing app #2334
- Update CODEOWNERS to include owners of specific samples #2525
- Audit remaining samples, and improve if necessary