diff --git a/src/adoptawidget/images/image1.png b/src/adoptawidget/images/image1.png new file mode 100644 index 0000000000..55f0feec0f Binary files /dev/null and b/src/adoptawidget/images/image1.png differ diff --git a/src/adoptawidget/images/image2.png b/src/adoptawidget/images/image2.png new file mode 100644 index 0000000000..742e978c6e Binary files /dev/null and b/src/adoptawidget/images/image2.png differ diff --git a/src/adoptawidget/index.md b/src/adoptawidget/index.md new file mode 100644 index 0000000000..0e64ef4c99 --- /dev/null +++ b/src/adoptawidget/index.md @@ -0,0 +1,285 @@ +--- +title: Adopt a Widget +layout: default +show_banner: False +--- + +Adopt a Widget logo + +Flutter is an open source project hosted [on +GitHub](https://github.com/flutter/flutter), and making the documentation better +helps everyone! So, for the month of November, we’re extending a special +invitation to contribute to the Flutter project by choosing a Widget and +improving its API documentation. + +## How to contribute {#how-to-contribute} + +1. Go to [this list of +issues](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22adopt+a+widget%22+no%3Aassignee) +and choose an issue. You can only be assigned one Adopt A Widget issue at a +time, so pick your favorite! +2. Leave a comment on the issue, asking to be assigned. The first person to +respond will be assigned. For example: +Ask to be assigned +3. Once you are assigned, set up your environment, make the change, and submit +the pull request. If you're not sure how to do this, see the +[Quickstart](#quickstart) below. + +The +[CONTRIBUTING](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md) +doc has details on contributing to Flutter. + +## Discord {#discord} + +Join the [#AdoptAWidget channel on the Flutter Discord +server](https://discord.com/channels/608014603317936148/771798504355528704) to +ask questions and get help. + +## Guidelines + +**Wait to be assigned** + +If you aren't assigned to the issue, let the assignee fix it. Don't submit a +pull request for someone else's issue. + +**Respond within three days after being assigned** + +If we don't hear back from you, we might need to assign it to someone else. + +**One issue at a time** + +If you're already working on an issue, wait until it's closed before requesting +another. + +**Don't create "Adopt A Widget" issues** + +We are limiting AdoptAWidget to [this list of +issues](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22adopt+a+widget%22+no%3Aassignee). + +**Don't worry if you don't get assigned** + +There are plenty of other issues that can be fixed. You can also take a look for +[issues with the "d: api docs" +label](https://github.com/flutter/flutter/issues?q=is%3Aopen+is%3Aissue+label%3A%22d%3A+api+docs%22) +that need attention. + +**Be original** + +Don't copy code snippets or text from other sources like StackOverflow. + +## Ways to contribute {#ways-to-contribute} + +Each issue specifies what type of contribution we are looking for: + +* Adding code (either a [snippet](https://github.com/flutter/flutter/tree/master/dev/snippets#snippet-tool), [sample](https://github.com/flutter/flutter/tree/master/dev/snippets#sample-tool), or [DartPad](https://github.com/flutter/flutter/tree/master/dev/snippets#templates)) +* Adding references (e.g. "See also") +* Adding more explanation to the documentation + + +### Adding code {#adding-code} +There are three ways to contribute code: a `snippet`, a `dartpad`, or a +`sample`. For more details, see the [Dartdoc Generation +README](https://github.com/flutter/flutter/tree/master/dev/snippets). + +Please be cognizant that writing _sample_ code has a different goal (and some +additional constraints) compared to writing production code. Mozilla [has a good +overview](https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Code_guidelines#General_best_practices) +(the article is about the web, but 95% of it applies to any platform). + + +#### Snippets {#snippets} + +Snippets can be added using the following syntax: + +```dart +/// {@tool snippet} +/// +/// This is a comment explaining the snippet below: +/// +/// ```dart +/// MyWidget( +/// color: Colors.green, +/// ) +/// ``` +/// {@end-tool} +``` + +#### Sample {#sample} + +Samples are snippets of code that are wrapped with a template, so you don't have +to write boilerplate code. The `--template` can be any of the templates found in +the snippet tool's [templates +directory](https://github.com/flutter/flutter/tree/master/dev/snippets/config/templates). + +```dart +/// {@tool sample --template=stateless_widget_scaffold_center} +/// +/// This is a comment explaining the snippet below: +/// +/// ```dart +/// Widget build(BuildContext context) { +/// return MyWidget( +/// color: Colors.green, +/// ); +/// } +/// ``` +/// {@end-tool} +``` + +#### DartPad sample {#dartpad-sample} + +To add a sample that runs in DartPad, use `{@tool dartpad}` and provide the same +templates found in the [templates +directory](https://github.com/flutter/flutter/tree/master/dev/snippets/config/templates): + + +```dart +/// {@tool dartpad --template=stateless_widget_material} +/// +/// This is a comment explaining the snippet below: +/// +/// ```dart +/// Widget build(BuildContext context) { +/// return MyWidget( +/// color: Colors.green, +/// ); +/// } +/// ``` +/// {@end-tool} +``` + +### Adding References {#adding-references} + +If a Widget needs references, add a `See also:` section to the end of a widget's +documentation comment: + +```dart +/// Creates a route for the given route settings. +/// +/// Used by [Navigator.onGenerateRoute]. +/// +/// See also: +/// +/// * [Navigator], which is where all the [Route]s end up. +``` + +### Adding more explanation to the documentation {#adding-more-explanation-to-the-documentation} + +If a widget doesn't provide enough explanation, you can add more! You can +explain: + +* What it is +* What it enables you to do +* How to use it +* The behavior of the widget in certain situations +* Other important information about the widget + +See the [Documentation +section](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#documentation-dartdocs-javadocs-etc) +of the Flutter Style Guide and [Effective Dart: +Documentation](https://dart.dev/guides/language/effective-dart/documentation) +for details on how to write great documentation. + +## Quickstart {#quickstart} + +### Get the code {#get-the-code} + +To get started, fork the SDK and use Git to fetch a local copy: + +1. Install dependencies listed in + [Setting up the Framework development environment](https://github.com/flutter/flutter/wiki/Setting-up-the-Framework-development-environment) +2. Fork the flutter repo +[https://github.com/flutter/flutter](https://github.com/flutter/flutter). For +more information, see [GitHub's official +instructions](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo). +3. Clone your fork: `git clone +https://github.com/<your_name_here>/flutter.git` +4. Change directory: `cd flutter` +5. Add an upstream remote: `git remote add upstream +git@github.com:flutter/flutter.git` +6. Run `flutter update-packages` to fetch all the Dart packages that Flutter +uses. + + +### Open the code in your IDE {#open-the-code-in-your-ide} + +In IntelliJ or VSCode, open `packages/flutter`, where most of the Flutter +framework code lives. + + +### Make the change {#make-the-change} + +Open the file listed in the issue and update the documentation comment. See +"Ways to contribute" for examples. + +### Analyzing and Generating API Docs + +Running this command from the root directory analyzes and generates the +documentation. This command can take up to 20 minutes to complete, so double +check your changes first. If you want, you can also [analyze +snippets](https://github.com/flutter/flutter/tree/master/dev/snippets#running-sample-analysis-locally) +directly. + +```bash +./dev/bots/docs.sh +``` + +To view the generated docs, open `dev/docs/doc/api/index.html`. + +{{site.alert.note}} + Flutter API docs cannot be generated on Windows. If you are using + Windows, you may need to download the Linux version of the SDK and use the + [Windows Subsystem for + Linux](https://docs.microsoft.com/en-us/windows/wsl/about). +{{site.alert.end}} + +For more information, see the [Dartdoc Generation +README](https://github.com/flutter/flutter/tree/master/dev/snippets). + +### Commit the change {#commit-the-change} + +Modify the documentation and commit the change: + + +```bash +git checkout -b update-builder-widget +git add -A +git commit -m "Update Builder API Docs" +git push origin update-builder-widget +``` + +### Make a Pull request {#make-a-pull-request} + +Make a pull request with `AdoptAWidget: WidgetName` in the title, and fill out +this template: + +```markdown +AdoptAWidget: Builder + + + + +This pull request is: + +- [x] A code sample +- [ ] More references +- [ ] More explanation + + +closes #1234 + +``` + +{{site.alert.note}} + If you are a first-time contributor to this repo, you will be asked to sign + Google's [Contributor License + Agreement](https://cla.developers.google.com/about/google-corporate). +{{site.alert.end}} + +## More resources + +* [Setting up the framework for developement](https://github.com/flutter/flutter/wiki/Setting-up-the-Framework-development-environment) +* [CONTRIBUTING](https://github.com/flutter/flutter/blob/master/CONTRIBUTING.md) +* [Dartdoc Generation](https://github.com/flutter/flutter/tree/master/dev/snippets) +* [Flutter Style Guide - Documentation](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#documentation-dartdocs-javadocs-etc) +* [Effective Dart - Documentation](https://dart.dev/guides/language/effective-dart/documentation)