Skip to content

Latest commit

 

History

History
333 lines (252 loc) · 11.4 KB

README.md

File metadata and controls

333 lines (252 loc) · 11.4 KB
Raw

Flutter logo

Flutter website

Build Status OpenSSF Scorecard

Table of contents

Issues, bugs, and requests

We welcome contributions and feedback on our website. Please file a request in our issue tracker or create a pull request. For simple changes (such as tweaking some text), it's easiest to make changes using the GitHub UI.

If you have an issue with the API docs on api.flutter.dev, please file those issues on the flutter/flutter repo, not on this (flutter/website) repo. The API docs are embedded in Flutter's source code, so the engineering team handles those.

Before you submit a PR

We love it when the community gets involved in improving our docs! But here are a few notes to keep in mind before you submit a PR:

  • When triaging issues, we sometimes label an issue with the tag PRs welcome. But we welcome PRs on other issues as well— it doesn't have to be tagged with that label.
  • Please don't run our docs through Grammarly (or similar) and submit those changes as a PR.
  • We follow the Google Developer Documentation Style Guidelines — for example, don't use "i.e." or "e.g.", avoid writing in first person, and avoid writing in future tense. You can start with the style guide highlights or the word list, or use the search bar that's at the top of every style guide page.

We truly thank you for your willingness and helpfulness in keeping the website docs up to date!

Before you build this site

For changes beyond simple text and CSS tweaks, we recommend building the site.

1. Get the prerequisites

Install the following tools, if you don't have them already:

  • bash, the Bourne shell
    These instructions assume you're using bash, and setup might not work if you use another shell.
  • GNU Make
    On Windows the easiest way to install Make is choco install make. Other options include using a subsystem.
  • Docker. We use Docker for local dev, tests, and building the site. Install it from https://docs.docker.com/get-docker/.
  • Firebase CLI, for hosting the site locally. One way to get this is to run npm install -g firebase-tools. For full setup details, read the Firebase CLI documentation.

2. Clone this repo and its submodules

Note: This repo has git submodules, which affects how you clone it. The GitHub documentation has general help on forking and cloning repos.

If you are working in the Windows desktop environment, make sure you have Git autocrlf set to input before initializing the submodules. This ensures that line endings are handled correctly before any Bash scripts are executed within the submodules. See issue 6201 for details.

If you're outside of the Flutter organization, we recommend you create a fork of the repo under your own account, and then submit a PR from that fork.

Once you have a fork (or you're a Flutter org member), choose one of the following submodule-cloning techniques:

  • Clone the repo and its submodule at the same using the --recurse-submodules option:

    $ git clone --recurse-submodules https://github.com/<username-or-flutter>/website.git

    OR

  • If you've already cloned the repo without its submodule, then run this command from the repo root:

    $ git submodule update --init --recursive

Note: At any time during development you can use the git submodule command to refresh submodules:

$ git pull; git submodule update --init --recursive

Setting up your local environment and serving changes

  1. Optional: After cloning the repo and its submodules, create a branch for your changes:

    $ git checkout -b <BRANCH_NAME>

  2. If the Docker Desktop application isn't already running, start it. Look at its status icon: if it has an exclamation point (!), then update Docker Desktop.

  3. Run the initial setup command:

    $ make setup

  4. Serve the site locally (via docker-compose):

    $ make up

    The site is generated, and then the development server runs in the Docker container, with the generated _site directory visible locally.

  5. View your changes in the browser by navigating to http://localhost:4002.

    Note: Unless you're editing files under site-shared, you can safely ignore ERROR: directory is already being watched messages. For details, see #1363.

  6. Make your changes. The files are updated, and your browser view should update to reflect the changes. You can either edit files locally or use an editor like vim directly in a shell in the container. To start a container shell, run docker-compose exec site bash.

    Tip: If you aren't seeing the changes you expect, restart the server and rebuild the site from scratch:

    $ make down && make clean && make up

    In some rare cases you might want to force all running containers down:

    $ docker rm -f $(docker ps -aq)

  7. Commit your changes to the branch and submit your PR.

  8. When you've finished developing, shut down the Docker container:

    $ make down

Tip: To find additional commands, read the Makefile. For example, if you need to debug the Docker infrastructure, you can run make debug.

Creating and/or editing DartPad example code

Most of the code used to create DartPad examples is hosted on GitHub. However, this repo also contains some *.dart files responsible for DartPad example code.

DartPad example code in GitHub gists

A typical DartPad example takes the form of an iframe, for example, within a codelab's Markdown file:

<iframe
  src="{{ site.custom.dartpad.embed-flutter-prefix }}?id=d7b09149ffee2f0535bb0c04d96987f5" 
  style="border:1px solid lightgrey;margin-top:10px;margin-bottom:25px"
  frameborder="no" height="500" width="100%">
</iframe>

This iframe depends on the following GitHub gist URL:

https://gist.github.com/d7b09149ffee2f0535bb0c04d96987f5

For detailed instructions on how to use this approach to DartPad examples, see the DartPad embedding guide.

DartPad example code in this repo

Some DartPad example code remains in this repo:

  • src/_packages/dartpad_picker/web/dartpad_picker_main.dart

This code must be manually compiled, which also regenerates the associated JavaScript file in src/assets/js:

$ cd src/_packages/dartpad_picker
$ ./compile.sh

Deploying to a staging site

You can deploy your local edits to a personal staging site as follows.

  1. If you don't already have a Firebase project, navigate to the Firebase Console and create your own Firebase project (for example, my-foo).

  2. In a separate bash shell, change to the repo directory and initialize Firebase:

    $ npx firebase init

  3. If you created a new project, add it using the firebase use command:

    $ npx firebase use --add
? Which project do you want to add? <select the project you created>
? What alias do you want to use for this project? (e.g. staging) my-foo

  1. Tell Firebase that you want to deploy to your project:

    $ npx firebase use my-foo
Now using alias staging (my-foo)

  2. Build the site via Docker with:

    $ make build

    The _site directory refreshes locally.

  3. Deploy to the staging site:

    $ make deploy

    Your personal version of the Flutter website ow deployed to Firebase. Copy the serving URL from the command output.

Refreshing code excerpts

A build that fails with the error => ERROR: some code excerpts were not refreshed! means that one or more code excerpts in the markdown file aren't identical to the code in the corresponding .dart file.

To resolve this error, from the root of the website directory, run ./tool/refresh-code-excerpts.sh.

For more information see Code excerpts .

Writing for flutter.dev

The site-shared repo contains infrastructure shared by most of our Dart and Flutter websites. Some of this README is in the doc directory in the site-shared repo.

For more information on using and writing for this repo, refer to the following docs: