Skip to content

Latest commit

 

History

History
371 lines (282 loc) · 13 KB

README.md

File metadata and controls

371 lines (282 loc) · 13 KB
Raw

Flutter's website Flutter logo

Build Status

Table of contents

Issues, bugs, and requests

We welcome contributions and feedback on our website! Please file a request in our issue tracker and we'll take a look.

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.

NOTE: For simple changes (such as to CSS and text), you probably don't need to build this site. Often, you can make changes using the GitHub UI. If you want/need to build, read on.

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 realize that we follow (or try to follow) the Google Developer Documentation Style Guidelines. So please don't run our docs through Grammarly (or similar) and submit those changes as a PR. This guide is a reference doc and not meant to be read like a novel, but check out the highlights page or use the search bar to find your subject of interest. Also, the wordlist is very useful. (For example, don't use "i.e." or "e.g.", and avoid writing in first person.)

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

Before you build this 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 -- setup might not work if you use another shell.

  • nvm, the Node Version Manager.

    NOTE: To make nvm immediately available in your current shell, run source <PATH_TO_INSTALLATION>. For example:

    $ source ~/.nvm/nvm.sh

  • rvm, the Ruby Version Manager.

    NOTE: To make rvm immediately available in your current shell, run source <PATH_TO_INSTALLATION>. For example:

    $ source ~/.rvm/bin/rvm

  • Flutter (You get Dart when you get Flutter. Confirm with which flutter and which dart.)

  • GNU diffutils version 3.6 or later.

    NOTE: diff v3.6+ is required to ensure that in-page code diffs are consistently refreshed across macOS and Linux. Issue #3076 was due to the default macOS diff being at v2.x. To upgrade diffutils, run:

    $ brew install diffutils

IMPORTANT: Follow the installation instructions for each of the tools carefully. In particular, configure your shell/environment so that the tools are available in every terminal/command window you create.

2. Clone this repo and its submodules

NOTE: This repo has git submodules, which affects how you clone it.

To clone flutter/website (this repo), follow the instructions given in the GitHub help on Cloning a repository, then choose one of the following submodule-cloning techniques:

  • Clone this repo and its submodule at the same, use the --recurse-submodules option:

    $ git clone --recurse-submodules https://github.com/flutter/website.git

    OR

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

    $ git submodule update --init --remote

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

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

3. Run installation scripts

NOTE: It is safe to (re-)run all of the commands and scripts given below even if you already have the required packages installed.

Open a bash terminal/command window and execute the following commands:

  1. After you have cloned this repo, change to the root of this repo:

    $ cd <PATH_TO_REPO>

  2. Run the env-set.sh script to initialize environment variables, and to install/use required Node & Ruby version:

    $ source ./tool/env-set.sh

  3. Run before-install.sh to install the core set of required tools:

    $ ./tool/before-install.sh

  4. Run install.sh to install everything else needed to build this site:

    $ ./tool/install.sh

IMPORTANT:

  • Any time you create a new terminal/command window to work on this repo, repeat steps 1 and 2 above.

Developing and serving changes

  1. After you clone this repo, create a branch. For example:

    $ git checkout -b <BRANCH_NAME>

  2. Make your changes, then commit them to the branch.

  3. Test your changes by serving the site locally. To serve locally, run either one of these commands:

    • $ ./tool/serve.sh # or npm run start

    OR

    • $ bundle exec jekyll serve --incremental --watch --livereload --port 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.

      NOTE: The first time you run either one of these commands, Jekyll takes anywhere between 10-20 seconds to generate static content inside the _sites directory. If you try to verify the site locally, but aren't able to see the content right away, wait 20 seconds before stopping the server or concluding that something is wrong.

  4. Before submitting, validate site links:

    $ ./tool/shared/check-links.sh

TIP: Sometimes Jekyll gets confused and seems to be out-of-sync. (This might happen, for example, when you pull from master and lots of files have moved.) To fix Jekyll, stop the serve.sh script, remove the generated site files: hand, and then restart the serve.sh script:

$ npm run clean

OR

$ jekyll clean

OR

$ rm -Rf ./_site/* ./.jekyll*

Next, restart the serve.sh script:

$ npm run start

OR

$ ./tool/serve.sh

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 - src/_packages/dartpad_picker

Some DartPad example code remains in .dart files in this repo, and must be compiled via src/_packages/dartpad_picker/compile.sh. For an example, consult src/_packages/dartpad_picker/web/dartpad_picker_main.dart.

In order to create or change example code using dartpad_picker, you must regenerate the JavaScript:

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

Deploy to a staging site

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

  1. Serve your changes locally, as previously instructed. Keep the serve.sh script running in its own bash shell.

  2. In the Firebase Console, create your own Firebase project (e.g. my-foo). You only need to do this step once.

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

    $ npx firebase init

  4. Tell Firebase about your project with the firebase use command You only need to do this step once:

    $ 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

  5. Tell Firebase that you want to deploy to staging:

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

  6. Tell Firebase to execute deployment of your project:

$ npx firebase deploy

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

Alternate deployment script

Alternatively, you can skip the previous steps and just use the deploy script:

$ ./tool/shared/deploy.sh --local my-foo

=== Deploying to '<your project name>'...

i  deploying hosting
i  hosting: preparing _site directory for upload...
✔  hosting: 213 files uploaded successfully
i  starting release process (may take several minutes)...

✔  Deploy complete!

Deploying to the official site

As of Feb 23, 2021, official site deploys are performed by GitHub Actions. In the event that you need to manually deploy, use the deploy script and the default project:

$ ./tool/shared/deploy.sh --local --robots ok default

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:

Also check out the site-shared wiki: