diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1a3d0b81863..68fdd7e8c6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,45 @@ # 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 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]_ + +
+ +# 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 -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. +## Is this the right place for your sample? -## 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 -of the samples already in the repo, **please -[file an issue](https://github.com/flutter/samples/issues/new) before you begin +of the samples already in the repo, **please [file an issue] before you begin 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 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 -[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 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 @@ -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 frustration later on. -## A few ground rules - -This is monorepo containing a bunch of projects. While different codebases have -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 -couple years keeping the repo tidy and running smooth. - -Each app should: - -* Be designed to build against the current - [stable](https://github.com/flutter/flutter/blob/master/docs/releases/Flutter-build-release-channels.md) - release of the Flutter SDK. -* 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. -* Have no analyzer errors or warnings. -* Be formatted with `dart format`. -* 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), - [beta](tool/flutter_ci_script_beta.sh), and [master](tool/flutter_ci_script_master.sh), - which runs the analyzer, the formatter, and `flutter test`. -* Add the new project directory to the [dependabot](.github/dependabot.yaml) configuration - to keep dependencies updated in an on-going basis. -* Avoid adding an onerous amount of blobs (typically images or other assets) to - the repo. - -In addition, sample code is, at the end of the day, still code. It should be -written with at least as much care as the Flutter code you'd find in the SDK -itself. For that reason, most of the -[Flutter style guide](https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md) -also applies to code in this repo. +
+ +# Contribute enhancements and fixes + +Enhancements and bug fixes are welcome and appreciated. +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. + +## Filing issues and evaluating existing samples + +You can also contribute by filing issues against existing samples. This is thankless work +and is _greatly_ appreciated. It's also a good way to familiarize yourself with the repository. + +To evaluate a sample for possible issues, use the [Sample checklist] below. + +
+ +# Writing a new sample + +Before filing an issue for a new sample or submitting a PR, you must read the rest of this page. + +## What is a sample? + +Samples are reference materials that teach developers how to solve a specific problem. +Samples contain **correct and concise code** that developers can +**quickly understand** and **easily reuse** with minimal side effects. + +### What samples should we have? + +Samples in this repo demonstrates how to **use current features** of the **Flutter and Dart SDKs** using **best practices**. +In other words, a sample should meet the following criteria: + +* 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.**
+ 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.**
+ 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.**
+ If it is, you should likely use a personal repository. + +5. **The sample isn’t tied to a library or package.**
+ 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.**
+ 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 -Projects in the repo's top-level `experimental` directory are allowed to skirt -some of the above rules. These apps are either experimental in nature or use -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. +The experimental folder is being deprecated. If you have an experiemental sample project, +you should manage it in a personal repository until it runs on the stable channel. + +
+ +# 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. +``` + +
-## Code reviews +# Code reviews All submissions, including submissions by project members, require review. @@ -107,7 +236,7 @@ primary maintainers, though, are: * [@domesticmouse](https://github.com/domesticmouse) * [@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, 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 reviewer. -## 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. -``` +
-## The small print +# The small print Contributions made by corporations are covered by a different agreement than the -one above, the -[Software Grant and Corporate Contributor License Agreement](https://developers.google.com/open-source/cla/corporate). +one above, the [Software Grant and Corporate Contributor License Agreement]. + +[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