Contents

Adopt a Widget

Contents

Adopt a Widget logo

Flutter is an open source project hosted on GitHub and the API docs (generated from the source code) are hosted on api.flutter.dev. Adopting a widget and improving its documentation 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.

Contributions

(Updated Feb 14, 2021)

How to contribute

  1. Go to this list of issues and choose one. You can only be assigned one Adopt A Widget issue at a time, so choose 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 guide below.

The CONTRIBUTING doc has details on contributing to Flutter.

Discord

Join the #AdoptAWidget channel on the Flutter Discord server 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.

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 that need attention.

Be original

Don’t copy code snippets or text from other sources like StackOverflow.

Ways to contribute

Each issue specifies what type of contribution we are looking for:

  • Adding code (either a snippet, sample, or DartPad)
  • Adding references (for example, under “See also”)
  • Adding more explanation to the documentation

Adding code

There are three ways to contribute code: a snippet, a dartpad, or a sample. For more details, see the Dartdoc Generation README.

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 (the article is about the web, but 95% of it applies to any platform).

Snippets

Snippets can be added using the following syntax:

/// {@tool snippet}
///
/// This is a comment explaining the snippet below:
///
/// ```dart
/// MyWidget(
///   color: Colors.green,
/// )
/// ```
/// {@end-tool}

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.

/// {@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

To add a sample that runs in DartPad, use {@tool dartpad} and provide the same templates found in the templates directory:

/// {@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

If a Widget needs references, add a See also: section to the end of a widget’s documentation comment:

/// 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

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 of the Flutter Style Guide and Effective Dart - Documentation for details on how to write great documentation.

Quickstart

Use the following instructions to get started.

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.
  2. Fork the Flutter repo. For more information, see GitHub’s official instructions.
  3. Clone your fork: `git clone https://github.com//flutter.git`</nobr>
  4. Change directory into the repo: 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

In IntelliJ or VSCode, open packages/flutter, where most of the Flutter framework code lives.

Make the change

Open the file listed in the issue and update the documentation. 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 directly.

./dev/bots/docs.sh

To view the generated docs, open dev/docs/doc/api/index.html.

For more information, see the Dartdoc Generation README.

Commit the change

Modify the documentation and commit the change:

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 with AdoptAWidget: WidgetName in the title, and fill out this template:

AdoptAWidget: Builder

<!-- Provide an explanation of the change -->

<!-- Specify what this pull request does -->
This pull request is:

- [x] A code sample
- [ ] More references
- [ ] More explanation

<!-- Add the AdoptAWidget issue that is assigned to you: -->
closes #1234

Resources