msb-public
/
samples
mirror of https://github.com/flutter/samples.git
1
0
Code Issues Projects Releases Wiki Activity

Update contributing guidelines for repository (#2500)

Browse Source 
Update contributing guidelines to reflect new policies for 2025.
Related to #2497, but does not complete it.


## Pre-launch Checklist

- [x] I read the [Flutter Style Guide] _recently_, and have followed its
advice.
- [x] I signed the [CLA].
- [x] I read the [Contributors Guide].
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] All existing and new tests are passing.
pull/2501/head
Eric Windmill 4 weeks ago committed by GitHub
parent 16c3c021e8
commit c6c931801a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 209 additions and 74 deletions
Show Stats Download Patch File Download Diff File

283
CONTRIBUTING.md
Unescape View File

@ -1,46 +1,45 @@
# Contributing # Contributing
_See also: [Flutter's code of conduct](https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md)_
Want to contribute to the Flutter sample ecosystem? Great! First, read this Want to contribute to the Flutter sample ecosystem? Great! First, read this
page (including the small print at the end). page (including the small print at the end).
## Is this the right place for your contribution? Do you work at Google? Great! You should **definitely** read this page before submitting a PR :)
* [Before you contribute]
* [Contribute enhancements and fixes]
* [Write a new sample]
* [Sample checklist]
_See also: [Flutter's code of conduct]_
<br />
# Before you contribute
This repo is used by members of the Flutter team and a few partners as a place
to store example apps and demos. It's not meant to be the one and only source of
truth for Flutter samples or the only place people go to learn about the best
ways to build with Flutter. What that means in practice is that if you've
written a great example app, it doesn't need to be maintained here in order to
get noticed, be of help to new Flutter devs, and have an impact on the
community.
You can maintain your sample app in your own repo (or with another source ## Is this the right place for your sample?
control provider) and still be as important a part of the Flutter-verse as
anything you see here. You can let us know on the
[FlutterDev Google Group](https://groups.google.com/forum/#!forum/flutter-dev)
when you've published something and Tweet about it with the
[#FlutterDev](https://twitter.com/search?q=%23FlutterDev) hashtag.
## So what should be contributed here, then? In most cases, if you've written a great sample app, it should be maintained
in your own repoistory. You can maintain your sample app in your own repo
(or with another source control provider) and still be as important a part of
the Flutter-verse as anything you see here.
Fixes and necessary improvements to the existing samples, mostly. **What should be contributed here, then?**
## Before you contribute Fixes and necessary improvements to the existing samples, mostly.
### File an issue first! ## File an issue first!
If you see a bug or have an idea for a feature that you feel would improve one If you see a bug or have an idea for a feature that you feel would improve one
of the samples already in the repo, **please of the samples already in the repo, **please [file an issue] before you begin
[file an issue](https://github.com/flutter/samples/issues/new) before you begin
coding or send a PR**. This will help prevent duplicate work by letting us know coding or send a PR**. This will help prevent duplicate work by letting us know
what you're up to. It will help avoid a situation in which you spend a lot of what you're up to. It will help avoid a situation in which you spend a lot of
time coding something that's not quite right for the repo or its goals. time coding something that's not quite right for the repo or its goals.
### Sign the license agreement. ## Sign the license agreement.
Before we can use your code, you must sign the Before we can use your code, you must sign the
[Google Individual Contributor License Agreement](https://cla.developers.google.com/about/google-individual) [Google Individual Contributor License Agreement]
(CLA), which you can do online. The CLA is necessary mainly because you own the (CLA), which you can do online. The CLA is necessary mainly because you own the
copyright to your changes, even after your contribution becomes part of our copyright to your changes, even after your contribution becomes part of our
codebase, so we need your permission to use and distribute your code. We also codebase, so we need your permission to use and distribute your code. We also
@ -54,47 +53,177 @@ us first through the issue tracker with your idea so that we can help out and
possibly guide you. Coordinating up front makes it much easier to avoid possibly guide you. Coordinating up front makes it much easier to avoid
frustration later on. frustration later on.
## A few ground rules <br />
This is monorepo containing a bunch of projects. While different codebases have # Contribute enhancements and fixes
different needs, there are a few basic conventions that every project here is
expected to follow. All of them are based on our experience over the last Enhancements and bug fixes are welcome and appreciated.
couple years keeping the repo tidy and running smooth. If you spot an [issue] that you might want to fix but aren't sure how to get started,
feel free to comment on the issue and tag @ericwindmill with questions.
Each app should:
## Filing issues and evaluating existing samples
* Be designed to build against the current
[stable](https://github.com/flutter/flutter/blob/master/docs/releases/Flutter-build-release-channels.md) You can also contribute by filing issues against existing samples. This is thankless work
release of the Flutter SDK. and is _greatly_ appreciated. It's also a good way to familiarize yourself with the repository.
* Include the top level
[`analysis_options.yaml`](analysis_options.yaml) To evaluate a sample for possible issues, use the [Sample checklist] below.
file used throughout the repo. This file include a base set of analyzer
conventions and lints. <br />
* Have no analyzer errors or warnings.
* Be formatted with `dart format`. # Writing a new sample
* Include at least one working test in its `test` folder.
* Be wired into the list of projects in the CI scripts for [stable](tool/flutter_ci_script_stable.sh), Before filing an issue for a new sample or submitting a PR, you must read the rest of this page.
[beta](tool/flutter_ci_script_beta.sh), and [master](tool/flutter_ci_script_master.sh),
which runs the analyzer, the formatter, and `flutter test`. ## What is a sample?
* Add the new project directory to the [dependabot](.github/dependabot.yaml) configuration
to keep dependencies updated in an on-going basis. Samples are reference materials that teach developers how to solve a specific problem.
* Avoid adding an onerous amount of blobs (typically images or other assets) to Samples contain **correct and concise code** that developers can
the repo. **quickly understand** and **easily reuse** with minimal side effects.
In addition, sample code is, at the end of the day, still code. It should be ### What samples should we have?
written with at least as much care as the Flutter code you'd find in the SDK
itself. For that reason, most of the Samples in this repo demonstrates how to **use current features** of the **Flutter and Dart SDKs** using **best practices**.
[Flutter style guide](https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md) In other words, a sample should meet the following criteria:
also applies to code in this repo.
* Demonstrates _how to use the SDKS_ rather than show an end-product.
* Covers a critical developer journey in the SDK that is useful to >80% of developers.
* Prefers primitives in the SDK over libraries.
* Demonstrates features available on the stable channel of Flutter.
These guidelines can be broken in rare cases. For example, this is likely the best place in the
Flutter github org for demo apps, but those demo apps must be justified.
## Is this the right place for your sample? (revisited)
Validate your idea against the following criteria:
1. **The sample solves a single problem or set of tightly coupled problems.** <br/>
If not, you're either writing a Demo app or an extended sample. These might
still be appropriate for the samples repos, but need to be justified.
2. **The target audience for the sample isn’t beginners.**
3. **The sample code isn’t so complex that it needs video or text explanation.** <br />
Samples are reference materials, and the code should speak for itself. If either of these aren't true,
you may prefer to write a blogpost or tutorial.
5. **The sample isn’t tied to an event.** <br />
If it is, you should likely use a personal repository.
5. **The sample isn’t tied to a library or package.** <br />
If it is, the usage example should likely be in the [repository of that package].
6. **The topic doesn’t have crossover with any existing samples.** <br />
If it does, ensure that it wouldn't be better to update the existing sample.
## What are your ongoing maintenance resposibilities?
All sample code has an unbound maintenance cost. If you cannot commit to maintaining a sample
(for the forseeable future, barring changes in life circumstances), then you should talk to the
[primary maintainers] of this project, particularly @ericwindmill, before submitting a PR.
Any new sample **must** have a CODEOWNER, and that owner is most likely you (the author).
## What type of sample are your writing?
This repository contains two types of sample apps: **quickstarts** and **demo apps**.
### Quickstarts
* **Purpose**: Provides starting points that a developer can extend.
Solves specific problems or implements generic app features.
* **Size**: <= 200 lines of code, not including boiler plate (guide, not rule)
* **Qualities:**
* Contains one feature or a small set of related features, but generally runnable.
* Generic and un-opinionated about the context in which it is used.
* Prioritizes being generic over best practices.
* The code is Copy+paste-able.
* In Flutter, this means that the code that is being demonstrated should be separated from and boiler plate (i.e. `runApp`)
* **Audience:**
* Developers with Flutter and Dart experience that don't need code explained to them.
* **Answers the questions:**
* “What’s the minimal amount of code needed to implement this feature…”
* “... so I can understand how it works?”
* “... so I can understand how to add it to my app?”
* “How can I make sure I know how to extend this feature without missing anything?”
* "What code should I use as a starting point given I want to solve a very similar problem?"
### Demo apps
* **Purpose**: Meant to be built and ran. Demos the _product_, not how to write code.
* **Criteria**: Demo apps _only_ belong here if they...
* ...aren't tied to an event or moment in time.
* ...aren't tied to another resource (website, workshop, etc).
* ...don't require explanation (other than a short README).
* ...aren't primarily used to demonstrate an SDK feature.
### Other sample types
Other sample types, like demo apps that accompany docs or events, do not belong in this repository.
They should be maintained alongside the accompanying resources (i.e. in the website repository), or in a personal repository.
### The `experimental` folder ### The `experimental` folder
Projects in the repo's top-level `experimental` directory are allowed to skirt The experimental folder is being deprecated. If you have an experiemental sample project,
some of the above rules. These apps are either experimental in nature or use you should manage it in a personal repository until it runs on the stable channel.
APIs that haven't landed in the SDK's `stable` channel. They build against
`main`, and aren't (by default) wired into our CI system. <br />
# Sample checklist
Every piece of code will have value to someone, but it is easy for maintenance costs to grow over time.
The more items checked on this list, the higher the value and lower the maintenance costs.
Use this checklist to write new samples and evaluate existing ones.
**NB:** Demo apps have looser requirements. Use your best judgement when following the guidelines.
* Code
- [ ] Be designed to build against the current [stable]
release of the Flutter SDK.
- [ ] Sample is the only one for the API in question (across all Dash samples)
- [ ] Repository and pubspec name are titled for its ingredients (i.e. mvvm_architecture instead of compass_app)
- [ ] Only includes the minimal required code to demonstrate the feature or API and run the code.
- [ ] Sample favors 1P dependencies over 3P.
- [ ] Code has been sufficiently explained with doc comments.
- [ ] The sample app separates its bespoke code from general Flutter or Dart code.
- [ ] Favor readability over best practices unless readability requires an anti pattern. Use your best judgment.
- [ ] Avoid adding an onerous amount of blobs (typically images or other assets) to the repo.
- [ ] All files in the project must start with the appropriate [file headers].
* Tests, style and maintenance
- [ ] Sample has Dart tests that cover the business logic
- [ ] Sample is wired into the list of projects in the CI scripts for [stable](tool/flutter_ci_script_stable.sh),
[beta](tool/flutter_ci_script_beta.sh), and [master](tool/flutter_ci_script_master.sh),
which runs the analyzer, the formatter, and `flutter test`.
- [ ] Sample has a codeowner (it's likely you, the author)
- [ ] Sample is formatted with `dart format`.
- [ ] Sample has no analyzer errors or warnings.
- [ ] Add the new project directory to the [dependabot](.github/dependabot.yaml) configuration
to keep dependencies updated in an on-going basis.
- [ ] Follows the [Flutter style guide]
- [ ] Include the top level [`analysis_options.yaml`](analysis_options.yaml)
file used throughout the repo. This file include a base set of analyzer
conventions and lints.
* README
- [ ] Describes the apps design and purpose.
- [ ] Describes common errors and debugging steps.
- [ ] Describes any steps necessary to build and run.
- [ ] Has ‘Open in IDX’ button, and a nix file (if compatible with IDX).
## File headers
All files in the project must start with the following header.
```
// Copyright 2024 The Flutter team. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
```
<br />
## Code reviews # Code reviews
All submissions, including submissions by project members, require review. All submissions, including submissions by project members, require review.
@ -107,7 +236,7 @@ primary maintainers, though, are:
* [@domesticmouse](https://github.com/domesticmouse) * [@domesticmouse](https://github.com/domesticmouse)
* [@ericwindmill](https://github.com/ericwindmill) * [@ericwindmill](https://github.com/ericwindmill)
You are free to add one of these folks (particularly @RedBrogdon) as a reviewer You are free to add one of these folks (particularly @ericwindmill) as a reviewer
to any PR sent to this repo. We're happy to comment, answer (or ask) questions, to any PR sent to this repo. We're happy to comment, answer (or ask) questions,
and provide feedback. and provide feedback.
@ -121,18 +250,24 @@ before, or changing something that's a meta-concern like the CI setup, web
hosting, project setup, etc., please include one of the primary maintainers as a hosting, project setup, etc., please include one of the primary maintainers as a
reviewer. reviewer.
## File headers <br />
All files in the project must start with the following header.
```
// Copyright 2024 The Flutter team. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
```
## The small print # The small print
Contributions made by corporations are covered by a different agreement than the Contributions made by corporations are covered by a different agreement than the
one above, the one above, the [Software Grant and Corporate Contributor License Agreement].
[Software Grant and Corporate Contributor License Agreement](https://developers.google.com/open-source/cla/corporate).
[Flutter's code of conduct]: https://github.com/flutter/flutter/blob/master/CODE_OF_CONDUCT.md
[Before you contribute]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#before-you-contribute
[Contribute enhancements and fixes]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#contribute-enhancements-and-fixes
[Write a new sample]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#write-a-new-sample
[Sample checklist]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#samples-checklist
[file headers]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#file-headers
[Software Grant and Corporate Contributor License Agreement]: https://developers.google.com/open-source/cla/corporate
[issue]: https://github.com/flutter/samples/issues
[file an issue]: https://github.com/flutter/samples/issues/new
[repository of that package]: https://dart.dev/tools/pub/package-layout#examples
[stable]: https://github.com/flutter/flutter/blob/master/docs/releases/Flutter-build-release-channels.md
[Flutter style guide]: (https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md)
[Google Individual Contributor License Agreement]: https://cla.developers.google.com/about/google-individual
[primary maintainers]: https://github.com/flutter/samples/blob/main/CONTRIBUTING.md#code-reviews

Write Preview
Loading…
Cancel
Save