☂️ Migrate samples to 'quickstart' format, update and deprecate samples as necessary
- Dominant language
- Dart
- Stars
- 19.3k
- Forks
- 7.9k
- Avg merge
- 3h 26m
- Merged PRs (30d)
- 3
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](https://github.com/flutter/samples/blob/main/CONTRIBUTING.md).
For Googlers with too much time on their hands, read the long version of the motivation at go/dash-sample-code
## Motivations
1. **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.
2. **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.
3. **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.
4. **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
* #2509
* **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)
* #2511
* **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.
* #2512
* **desktop-photo-search** - Expand to mobile and web, maybe simplify business usecase logic. rename something like 'multiplatform_sample'.
* #2513
* **platform_design** This sample should be rolled into above.
* **navigation_and_routing** - This will be split up and simplified.
* #2514
### Samples to add
* cupertino_gallery - This should be similar to material_3_demo.
* #2519
* navigator 2.0
* #2518
### Samples to deprecate
* **asset_transformation** - This should be demonstrated in the package repository
* #2522
* **code_sharing** - This topic is well documented in the new architecture guidance docs and sample
* #2523
* **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)
* #2521
* **Deeplink-store-example** -> Deprecate in favor of the go_router example that includes deep-linking
* #2516
* **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
* #2520
* **Flutter-maps-firestore** - Quickstarts should sample one feature
* #2524 * **Form app** - Deprecate, as this is covered in the documentation
* **game_template** - This is being deprecated in favor of the flutter/games repository
* #2526
* **homescreen_widgets** - this should live in the package repository
* #2527
* **infinite_list** - This is thoroughly covered on docs.flutter.dev
* #2533
* **place_tracker** - Overly complex, redundant to other google_maps samples
* #2528
* **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
* #2529
* #2530
* **simplistic_calculator** - We don't need multiple samples demoing desktop functionality
* #2531
* **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.
* #1838
### TBD
* **simplistic_editor** - important, but way complex. idk
### Repo improvements, etc
* #2499
* #2507
* #2334
* #2525
* Audit remaining samples, and improve if necessary
Contributor guide
Assessment
This issue has not been assessed yet.