flutter / flutter/samples

☂️ Migrate samples to 'quickstart' format, update and deprecate samples as necessary

Open
#2,409 1 comment 1 reaction 1 assignee Claimed by @ericwindmill View on GitHub
p1 proposal tech-debt
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.